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If you have any comments or suggestions regarding either the 
Macintosh 68000 Development System software or this documentation, 
please send comments to 


Macintosh Development Tools 
Apple Computer, Inc. 

Mail Stop 2T 

20525 Mariani Avenue 
Cupertino, CA 95014 


Your input is extremely valuable in helping us to provide you with 
the best development tools possible. 
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About This Chapter 


This chapter introduces you to the Macintosh 68009 Development System. 
You should be familiar with the use of Macintosh: how to point, click, 
and select. If you aren't, read Macintosh, your owner's guide. It 
introduces you to the Finder, the application that manages your 
documents, and to the basic methods for using a Macintosh application. 


You should also be familiar with the assembly language of the Motorola 
MC68ØØØ, the microprocessor used in the Macintosh. If you aren't, read 
the M68ØØØ 16/32-Bit Microprocessor Programmer's Reference Manual, 
supplied with this package. For brevity, this manual will hereafter be 
referred to as the 68000 Reference Manual. For the same reason, the 
MC68ØØØ microprocessor will be referred to as the 6890969. 


Programming the Macintosh in assembly language is not a simple task. 
It requires detailed and thorough knowledge of the Macintosh. The 
Inside Macintosh manual provides all the technical information 
programmers need to create Macintosh applications. In places this 
manual assumes you are familiar with certain aspects of the Macintosh. 
Please refer to Inside Macintosh when you come across such passages. 


To help you launch your Macintosh programming career, thís development 
System contains an application that displays a menu bar and a window, 
and lets you edit within the window. A listing of the program, called 
Window, is in an appendix; the source for the program ís on disk. The 
importance of this program cannot be over-stressed. It shows how to 
initialize and use Macintosh ROM routines, how to support desk 
accessories from your application, and how to support multiple windows 
from an application. Sample desk accessories are also on the disk. 


The following Inside Macintosh chapters are particularly helpful: 


- Inside Macintosh: A Road Map. This chapter contains a sample 
program similar to the Window program but easier to understand 
since it is written in Pascal. 


- Programming Macintosh Applications in Assembly Language.  Thís 
chapter explains the use of the Toolbox and Operating System 


routines in the Macintosh. It describes how to pass parameters to 
the routines, how to call the routines, how calls to the routines 
are dispatched, how the routines return results, and which 68906 
registers you can safely use. 


- The Structure of a Macintosh Application. This chapter is 


especially important for proper interaction between the 
application and the Fínder. 


- The Resource Manager: A Programmer's Guide. 


- The Segment Loader: A Programmer's Guide. 
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Overview 


The Macintosh 68000 Development System includes two disks, named MDS] 
and MDS2. These dísks contain a host of useful applications and files. 
To acquaint you with the Macintosh 68009 Development System, these 
files are described below. MDS! is the disk that should be placed ín 
the built-in drive when you start up the development system. In 
general it contains the main applications províded with the system. 


=[ ] MDS1 
9 items 362K in disk 37K available 


ep ÅR 


ra 


Edit Asm Link Exec RMaker 


A E C1 C3 


PackSyms MacDB Nubs Empty Folder System Folder wa 





- Edit is the Editor. It is the applicacion with which you enter 
Assembler, Linker, Exec, and RMaker source files. 


- Asm is the Assembler. It translates assembly-language source 
files into relocatable modules that can be linked together into 
one application. 


- Link is the Linker. It connects modules produced by the Assembler 
together into one application. 


- Exec is the Executive. It automates and integrates assembling, 
linking, and the adding of resources to your application. 


- RMaker is the Resource Compiler. It uses the instructions in a 
text file to create a resource file. 


- PackSyms is an application that converts a symbol file into a 
packed symbol file. The use of packed symbol files saves memory, 
time, and disk space. 


- MacDB Nubs is a folder. It contains small programs (Nubs) that 
should be run on the same Macintosh as the program being debugged. 


- System Folder and Empty Folder contain their usual files. 
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MDS2 contains debuggers, sample programs, and useful system definition 
files. 


EEE nr 
6 items 393K in disk TK available 


AS 


|] | | 


Empty Folder Sample Programs Debuggers 


ss s | 


Trap Files Equ Files D Files 





- Debuggers is å folder that contains several Debuggers, providing 
various levels of assembly-language debugging tools 


- Sample Programs is a folder that contains a sample program, some 
sample desk accessories, a sample window definition procedure, and 
their associated files. An example given later in this chapter 
uses files from this folder. 


- Trap Files is a folder. The files in this folder assign trap 
numbers to trap names. These trap names and numbers are listed in 
an appendix. The traps are described in Inside Macintosh. 


- Equ Files is a folder. The files in this folder assign values to 
the constants and absolute memory locations used by the system. 
These constants are described in Inside Macintosh, and can help 
you avoid using incorrect values in your applications. 


- .D Files is a folder that contains packed versions of the files in 
the Trap Files and Equ Files folders. These are the files you 
will probably use with your application. 


- Empty Folder is devoid of the usual files. 
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Many files are used and created by the various applications in the 
Macintosh 68090 Development System. A file naming convention helps you 
and applications identify the creator and contents of otherwise similar 
files. Each kind of file has a unique extension -- a period followed 
by a few letters —- appended to the main part of {ts name. Thus, 
different yet related files are logically associated because they have 
the same base name. For example, 


- Curve.Asm is an assembly-language source file. 


- Curve.Err is a list of errors generated by the Assembler when it 
assembles Curve.Asm. 


A list of all the file extensions is given in the Quick Reference 
appendix. 


The development system is able to create three physically different 
types of files: application files, text files, and binary files. These 
three file types are designated by the following icons: 


[^ La 
coor 
10110 
5101 


Application Text File Binary File 


When using the Macintosh, you generally don't need to worry about the 
names of volumes. However, when using the Macintosh 68999 Development 
System you must sometimes specify volume names. For example, Linker 
control files list the files to be linked. Files mentioned by file 
name only are taken from the volume that contains your Linker control 
file. To specify another volume, use the form: 


Volume Name : FileName 


A colon separates the volume's name from the file's name. 


(warning) 
The development system uses a space to indícate the end 
of a file name and a period to indicate a file's 
extension. Avoid using these two characters in volume 
names. 
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The Editor 





The Editor is used for entering text. Documents created by the Editor 
are used as assembly-language source files, Linker control files, 
Executive control files, and Resource Compiler input files. 


The Editor doesn't provide any of the sophisticated text formatting 
functions available with programs such as MacWrite. It does, however, 
save text as documents of a type known as text-only files. These 
documents can be shared with all other programs that use text-only 
files or that let you paste text from the clipboard. For example, 
documents created by the Editor can be "prettied up" using MacWrite. 
Editor document names should be given the following extensions: 


- .Asm to indicate the main source file for an assembly 


- „Files to indicate a file that contains a list of separate 
assemblies to be performed 


- „Link to indicate a Linker control file 
- „Job to indicate an Executive control file 
- .R to indicate a Resource Compiler source file 


The Editor is described in Chapter 2. 


Assembly language 
source files 


window .Asm 


= Linker control 
Ñ files 
Window Link 


Edit ° Executive control 
is used to files 


create... Window .Job 


IN 
Resource Compiler 
source files 


Window R 
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The Assembler 


The Assembler translates 68000 assembly-language source documents into 
files containing relocatable code and symbol table information. Such 

files are given the extension «Rel. Rel files must be linked before 

an executable object file 1s produced. 


If errors occur during assembly, a list of the errors is placed in a 
.Err file. If a listing of the file is requested, it's placed in a 
«Lst file. 


The Assembler has the following special features: 


- Instructions can be grouped together into macros. Macros are 
invoked by name, and they can be given strings as parameters. 
Partial strings way be used within the macro. 


- It modífies some instructions so that your program can call, jump 
to, or branch to code in other relocatable segments. 


- Conditional assembly inetructions allow multiple versions of a 
program to be generated from a single source. 


The Assembler is described in Chapter 3. 


0001 Relocatable object 
module with symbol 


10110 10110 

ero ke " table information 
MacTraps.D Window Rel 

0001 isti 


10110 Listing of assembled 
01011 files, if requested 


ToolEqu.D ÁS window üÜ 


List of errors 
: encountered during 
Window .Asm È) assembly 
Traps, Equates, and 


source files are given 
as input to the Assembler 
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The Linker 





The Linker combines a number of .Rel files, produced by the Assembler, 
into an application file. An application's name has no extension. A 
symbol table, which is primarily used by the Debugger, is placed into a 
.Map file. If you request a Linker listing, it too ts placed into the 
‚Map file. 


The files to be linked together are specified in a Linker control file, 
created by the Editor, that has the .Link extension. This file also 
controls segmentation and listing of the program. 


Errors encountered during linking are automatically written to a .LErr 
file. 


The Linker is described in Chapter 4. 


object file 
(an application!) 


table information 


Relocatable object 
module with symbol Ra <A Executable 


Window Re! Winans 


f Symbol table 
and listing, 


if requested 
Window. i]- £ Map 


Linker control 
file. Specifies 
listing on or off 


Source file 
used if listing 
is requested 


List of errors 
from linking 


d Asm E]) 
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The Executive 

The Executive automates assembly, linking, and resource compilation. 
Control files, known as .Job files, determine the sequence of 
applications to be executed by the Executive. 

Each command in an Executive control file specifies not only what 
application is to be executed, but also what applications should be 
used upon successful and unsuccessful completion of that application. 


The Executive is described in Chapter 5. 


Exec.Job specifies 
the applications and 


i their input files 
ah 


Asm 


[55] 


Exec Job When done, control 
returns to Exec 


Choose Execute 
Exec Job from the 
Execute Menu 


RMaker 
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A Simple Sample Session 


Here's a typical session with the Editor, Assembler, and Linker. The 
named files actually exist in the Sample Program folder; you can try 
the example if you wish. 


1. Select the Editor; then, from the File menu, open the file 
Window.Asm on MDS2. This is the source file for the assembly. 


2. To see how errors are handled, enter the line "Syntax Error"; then 
save the updated file by choosing Save from the File menu. 


3. Assemble the file by choosing ASM MDS2:WINDOW.ASM from the 
Transfer menu. Window.Asm is assembled automatically. 


4. An error occurs in the assembly, so the Assembler places a list of 
errors in the file Window.Err. When the assembly is complete, the 
Editor is launched with the Window.Asm and Window.Err documents 
open. 


5. Select the faulty line and cut it from the document, then transfer 
back to the Assembler. This time Window.Asm assembles 
successfully, and the resulting relocatable code and symbol table 
is placed in Window.Rel. (The file Window.Err is automatically 
removed from the disk.) 


6. Because the assembly was successful, the Executive is launched. 
Transfer to Link. Select and open the file Window.Link, the 
Linker control file. The application produced by linking 
Window.Rel is called Window. The symbol table file is called 
Window.Map. 


The following diagram shows the files involved in this process (the 
error documents are removed when a successful assembly takes place). 


Sample Program 
45K in folder 27K available 


Q 


window Window.Asm Window Link Window. Job — Window R 


IN LN 
0001 
[0110 
01011 


Window Rel  window.Map Window Rsrc 
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The Debuggers 


Two families of debuggers are provided with the Macintosh 680400 
Development System. The first, and most powerful, is called MacDB. It 
is a two-machine debugger (either Macintosh or Lisa running MacWorks). 
The second, called MacsBug, works on a single Macintosh. 


MacDB and MacsBug have similar capabilities, but MacDB requires far 
less memory (and thus can be used to debug larger applications), it 


provides more information at any instant, and it's much easier to use. 


These debuggers are briefly described below. 


MacDB 





MacDB is the two-machine debugger. A small program called a Nub runs 
on the same machine as your application, MacDB runs on another machine, 
and the two machines are connected by a serial cable. The cable 
provided with the Development System is intended for debugging using 
two Macintoshes. The chapter on MacDB tells how to use MacDB with a 
Lisa. 


Several different Nubs are provided with the Development System. These 
various Nubs let you connect the machines using the printer port or the 
modem port, or allow you to debug your application using MacWorks. 
Features of MacDB include 
- Multiple memory display windows. Memory can be displayed as 
characters, words, long words, strings, or disassembled 
symbolically. System traps are displayed symbolically too. 
- Symbolic display of addresses. Memory addresses can be displayed 
in hexadecimal or as symbols, and you can use these symbols in 


expressions (for example, you can set the PC to START). 


- One or more register display windows. All registers and memory 
locations can be changed easily. 


- Multiple breakpoints can be set and cleared. 

- Instructions can be executed one at a time. 

- Memory search for patterns. 

- Special trace and break capability for system trap instructions. 
- Display and checking of the heap. 


- Display of linked lists. 
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Here is a typical MacDB display: 


€ Debug Run Bkpts Window Format symbols 
EE Registers = 


ESTART: JSR $34(PC > 7> IR4 1E : 
START+4: JSR $4ECPC» OOO0CROORS 19422: 
START+3 : JSR $56{PC > š: FFFF 0000 1R426 : 
START+C: OrawMenuBar BERE 6001 0024 1A42A: 
START+E : JSR $86 ¢PC > 0000 0024 tA42E : 
START+ 12: JSR $9EXPC > 0000 OOFF 18432 : 
STRRT * 16: MOVE.L $5D4(PC»5,-CR?) 0000 FFFF 14436: 
START+1A: TE Idle FFO3 tR43R : 
STRRT* (C : SystemTask 1A43E : 
START+ IE: CLR -<A?>? tA4 1E R6D4 18442 : 
START+20: MOVE *$FFFF,-CA?> 1A41 5ACS tA446: 
START+24: PER $2EEXPC > 5RBÓ 
STRRT*28: GetNextEvent R644 

*START+2A: MOVE (A?7>+,00 557A 
START+2C:  BEQ.S *$-18 
START+2E: JSR $9C<PC > 
START+32: BEQ.S *$-1E 
START+34: RTS 
INITMANAGERS : PER $-4<A5> 
IN| TMANA+4: Ini tGraf 
INITMANA+5: Ini tFont 
INITMANA+8: MOVE.L *$FFFF,DO 
INITMANA+E: FlushEvents 
INI TMANA+ 10: InitWindow 
INETMANA+ 12: Imi tMenus E 





MacDB is described in Chapter 6. 
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MacsBug 
The MacsBug debuggers are single-Macintosh debuggers. The different 
versions are for use on a 128K Macintosh, a 512K Macintosh, a Lisa 
running MacWorks, or a Macintosh connected to an external terminal. 
Features of MacsBug include 

- display and set bytes of memory 

- disassemble memory 

- display and set registers 

- set and clear up to eight breakpoints 

- tracing of single or multiple instructions 

- selective tracing of system traps 


- display and checking of the heap 


Here is a typical MacsBug display: 


400B12: PC SUBQ.H 481,0? 
PCz00MODBl2 SR-00002000 

pó-000000060 D1=464YFY2YA D2-8000678C 03=4Y64YFYZ4YA 
p4=00010000 D5=00000007 D6-0000005C 07200000004 
80200015168 Al=20010A78 A2=0001288A A3=00012804 
pe A5=00015CAA AG=00015156 R72000150F 


MacsBug is described in Chapter 7. 
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The Resource Compiler 


The Resource Compiler, named RMaker, is a tool that translates a 
sequence of resource definitions in a text file into a file that 
contains those resources. 

Features of RMaker include 


- predefined resource types 


definable resource types 


- the ability to include specific resources from other files, or 
entire resource files 


- visible display of the compilation process, with error reporting 


Here is a typical RMaker display: 


€ File Transfer 


StaticText s - 
15 20 36 300 Data Size: 334 


This sample program was written | Map Size: 134 
StaticText | Total Size: 468 


35 20 56 300 
just to prove it could be done! 


* WIND Resource *1 specifies the 
* for the window in which editir 
* cali to GetNewWindow. 


Type WIND 
1 





RMaker is described in Chapter 8. 
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System Definition Files 


Some of the most important tools available to assembly-language 
programmers are the system definition files. These files contain the 
values and addresses of the definitions available to the programmer. 


It's a good idea always to use these definition files and the symbolic 
names they contain, since some of these values may be subject to 
change. 


The system definition files provided with the development system are 


; directives into development system 
directives. 


SysEqu.Txt : Low-level equates and globals 
SysEqu.D ; Packed version of common ones 
SysEquX.D ; Packed version of all 
ToolEqu.Txt ; Toolbox equates and globals 
ToolEqu.D ; Packed version of common ones 
ToolEquX.D ; Packed version of all 
QuickEqu.Txt ; QuickDraw equates and globals 
QuickEqu.D ; Packed version of common ones 
QuickEquX.D : Packed version of all 
FSEqu.Txt ; File system equates and globals 
FSEqu.D ; Packed version of all 
PackEqu.Txt ; Package equates and globals 
PrEqu.Txt ; Printer equates and globals 
SysErr.Txt ; System error numbers 
SysTraps.Txt ; Low-level traps 
ToolTraps.Txt ; Toolbox traps 
QuickTraps.Txt ; QuickDraw traps 
PackMacs.Txt ; Package macros 
SANEMacs. Txt ; Numerics macros. See Inside Mac, 

; Apple Numerics Manual (#939-9247-A) 
MacTraps .D ; Packed version of SysTraps + 

; ToolTraps + QuickTraps 
MacDefs.Txt ; Macros translating Lisa-style 

; 


Be sure that the symbols you use in your programs are identical to the 
symbols in these files. The .Txt files can be loaded into the Editor 
for viewing ot printing. 


Packed symbol files are explained in the chapter on the Assembler. 
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About This Chapter 


This chapter describes the Editor, a general-purpose text editor. In 
the context of the Macintosh 68009 Development System, its primary uses 
are to enter and edit assembly-language programs, Linker control files, 
Executive control files, and RMaker input files. 


Files Required 


If you wish to move the Editor to another disk, you must move the file 

named Edit. If you wish to transfer from the Editor to the Assembler, 

the Linker, the Executive, or RMaker, those applications must be on the 
same disk. 


File Naming Conventions 


The following types of files are all created in the Editor, and should 
be given names with the designated extensions: 


+ Ágm is recommended for assembly-language source programs. 


«Files is recommended for a file that contains a list of .Asm files to 
be assembled. 


«Link is the extension for Linker control files. 
«Job is the extension for Executive control files. 
oR is the extension for RMaker input files. 


These extensions indicate types of files that are used as inputs to the 
Assembler, the Linker, the Executive, and RMaker. Other extensions, 
such as .Txt, .Equ, and .D, can be used to classify other files used in 
your assemblies. 


Invoking the Editor 


There are several ways to use the Editor: 
- From the Finder, select and open the application named Edit. 


- From the Finder, select and open a text file created by the 
Editor. You can open up to four files simultaneously by selecting 
a group of them (by Shift-clicking them or dragging across 
multiple icons) before opening one of them. All files created 
using the Editor can be selected, as can listing and error files 
generated by the Assembler and Linker. 


- Choose Edit from the Transfer option of the Assembler, the Linker, 
the Executive, or RMaker. 
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- Call Edit from an Executive control file, as described in 
Chapter 5. 


About the Editor 


The Editor is a disk-based editor. Thus it's capable of editing 
documents much larger than will fit in memory. When a document is 
open, you can use the scroll bars to move, both vertically and 
horizontally, through the document. The Editor brings new portions of 
the document into memory as they're needed. 


To create a new document, choose New from the File menu. 
There are several ways to open existing documents: 


~ To open an existing document, choose the uppermost Open command 
from the File menu. This opens a standard file selection box from 
which you select the file to be opened. All files with type 
'TEXT’ can be opened from this menu. 


- You can also open files (including non-text files) by selecting 
the name of the file in an open document, and then choosing the 
other Open command from the File menu. 


- Finally, you can open a document by typing Command-K followed by 
the name of the file to be opened (including volume name if 
needed), and pressing Return. This technique is not listed in a 
menu, and it gives no visual feedback until the file is opened or 
not found. 


As many as four such documents can be on the desktop at a time. When 
you quit the Editor or transfer to another application, the Editor 
gives you a chance to save each document that has been altered. 


Editor Documents 


Editor documents consist of lines of text that are separated by Return 
characters. The Editor has no tools for manipulating or organizing 
pages, paragraphs, sentences, or pictures. 


When you type long lines of text, characters may be placed past the 
right edge of the window. To see these characters, use the horizontal 
scroll bar. It is possible to type a line longer than can be seen 
using the scroll bar. The text on such lines is not lost, but neither 
is it visible. To see the whole line, insert a Return into the middle 
of the line, breaking the line into smaller pieces. 


If you choose Show Invisibles from the Format menu, the invisible 
characters (Space, Tab, and Return) are replaced by visible symbols. 
Choose Hide Invisibles to restore normal display. 
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The Editor displays an entire document in text of a single size and 
font. The Monaco font, a monospaced font, is the default. Different 
documents on the desktop can have different fonts and font sizes. 


Editing 


Editing involves inserting text at the insertion point and removing, 
moving, copying, or replacing a selection. Any character or sequence 
of characters in a document can be selected and edited. 


You can replace the selection by typing or pasting. You can remove, 
move, or copy the selection using commands from the Edit menu or their 
keyboard equivalents. Cut or copied selections can be pasted into 
another place in the document, into another window (such as the Find or 
Change window), or into another document altogether. 


You can find and change text using the Find and Change commands in the 
Search menu. These commands search for a specified string starting at 
the current insertion point. If the string is found, it's either 
selected and displayed or replaced. If not, a box is displayed to 
notify you that the string wasn't found. When you choose Find, the 
currently selected string is used as the default string to find. You 
can close the Find or Change boxes by choosing Hide Find or Hide Change 
from the Search menu. 


Tabs and Alignment 


The Editor has several features that help organize programs visually. 
Tab stops allow you to align columns of text at regular intervals 
across the page; the Set Tabs command in the Format menu lets you set 
the distance between tab stops. 


The Auto Indent command in the Format menu lets you turn Auto Indent on 
and off. If Auto Indent is on, the insertion point is automatically 
lined up with the leftmost edge of the previous line each time you 
press Return. To back the cursor up to the left edge of the screen, 
use the Backspace key. If Auto Indent is off, the insertion point is 
placed at the left margin. 


The Align command in the Edit menu aligns the left margins of all the 
lines in a selected block of text. The Move Left and Move Right 
commands, also in the Edit menu, move all the lines in a selected block 
of text one space left or right. If a proportional font is selected, 
the width of one space is usually quite small. The easiest way to move 
a block of text several spaces is to press the keyboard equivalent 
several times in succession. 
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Document Format 


Text created by the Editor is saved as a document file. A document 
file is a text-only file that can be used by other applications that 
use text-only files. For example, the Text Only option of MacWrite 
(see Save As in the MacWrite manual) creates text-only files that can 
be used by the Editor. 


A text-only file is a stream of ASCII characters. It contains Tab 
characters and Return characters, but no other formatting information. 


AAA 


Printing Documents nn e l... uuu. — 


There are two ways to print documents: 


- From the Editor, choose the Print command in the File menu. This 
prints the current document and returns to the Editor. 


- From the Finder, select the documents you wish to print, then 
choose Print from the File menu. This prints the selected files 
and returns to the Finder. 


Printing from the Editor uses the current printing format. To set the 
printing format, choose Printing Format in the Editor's File menu. 
After choosing this command, you are presented with a dialog box that 
lets you specify the size of paper you are using. Printing from the 
Finder displays the Printing Fornat box before the first document is 
printed. The settings you choose hold for all subsequent documents. 


A second dialog box, displayed for each document printed, lets you 
choose the print quality (High, Standard, or Draft), which pages to 
print, how many copies to print, and whether the paper is continuous or 
separate sheets. 


These two boxes are standard printing dialog boxes, and are discussed 
in some detail in the other manuals (for example, MacWrite). 
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The Assembler 
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Tee 
About This Chapter 


This chapter describes the Macintosh Assembler. The Assembler 
translates one or more text files into files that contain relocatable 
code and symbol table information. Once all the portions of a program 
have been assembled, they can be linked together into an application. 
Even an application generated from a single source file must be linked 
before it becomes an executable application. 


The first part of this chapter describes the Assembler and how to use 
it. The second part of the chapter tells the syntax of statements 
accepted by the Assembler. The next part of the chapter is a reference 
for commands to the Assembler. 


This chapter doesn't give extensive examples. An appendix contains a 
program listing that contains a variety of Assembler statements. Refer 
to this listing for examples of usage. 


a i — — — 
Files Required 


If you wish to move the Assembler to a different disk, you must move 
the file Asm to that disk. If you wish to transfer from the Assembler 
to other applications, those applications must also be on the disk. 





he 
File Naming Conventions 


Files used by the Assembler can be divided into two groups: those used 
as input to the Assembler, and those produced by the Assembler. The 
first two file extensions designate Assembler control files. .D files, 
described below, are also Assembler input files. 


. Asm is the recommended extension for assembly-language source 
programs. Text files of any name can be assembled. 


.Files is the extension for a file that contains a list of .Asm files 
to be separately assembled. 


The next file extension identifies files created by the PackSyms 
application. 


D 1S the recommended extension for symbol files. They may 
be text files containing lists of equates, or packed symbol 
files; the assembler knows how to handle both. Refer to the 
section on packed symbol files at the end of this chapter. 


The final four file extensíons are given by the Assembler to the files 
it creates. 


«Rel is the extension automatically assigned to every relocatable 
module generated by the Assembler. 
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«Lat designates listing files produced by the Assembler. 


.Err designates a file that contains the errors encountered during 
assembly of a program. 


. Sym designates a file of symbol table information. Refer to the 
.DUMP directive, below. 


Invoking the Assembler 


There are several ways to invoke the Assembler: 


~ From the Finder, select from one to four files then open the 
application named Asm. The selected files are automatically 
assembled, then control returns to the Finder. 


~ Choose Asm from the Transfer menu of another application. 


- Call Asm from an Executive control file, as described in 
Chapter 5. 


Using the Assembler 


The following sections contain an overview of the operation and 
features of the Assembler. They're intended to provide enough 
information that you can use the Assembler menus easily once you've 
read this chapter. 


Assembler Source Files 


Assembler source files are text~only files, as created by the Editor. 
They should be named with the extension .Asm. A source file that 
contains a list of .Asm files to be separately assembled should be 
named with the extension .Files. 


A text-only source file consists of a series of lines of text, 
separated by Return characters. These lines may be blank lines, 
comment lines, assembly-language instructions, or instructions that 
control the Assembler (assembler directives). The exact format of 
source file lines is described in later sections. 
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Selecting Listin tions 


There are two ways to select listing options for your program: by 
choosing commands in the Options menu, or by placing printing control 
directives into your source file. The printing control directives, 
described later in this chapter, override commands given from the 
Options menu. 


Before you actually assemble your program, you should select the type 
of program listing you want, if any. From the Options menu, you can 
choose No Listing, List to File, or List to Display. 


In the listings generated by the Assembler, addresses that aren't 
resolved until linking are displayed as lowercase x's. Certain 
instructions are marked by capital letters enclosed in parentheses. 
The following letters are used: | 


P PC relative instruction 
R Relocatable instruction 
X Instruction will be modified if it crosses a 


segment boundary. The opcode displayed in the listing 
is not necessarily the final opcode. 


This menu also contains two options that let you choose what will be 
placed in the .Rel file produced by the Assembler. If Normal Output is 
chosen, the minimum amount of information is written to the .Rel tile. 
If Verbose Output is chosen, information is written to the .Rel file 
that allows a Linker listing to be generated. If Verbose Output is 
turned on, the .Rel file is larger, the assembly takes longer, and 
linking takes longer. 


Selecting a Source File 


If the Assembler is selected from the Editor's Transfer menu while a 
document having the extension .Asm is the current window, that document 
is automatically assembled. When you do this, No Listing and Normal 
Output are always selected. 


Otherwise, choose Select Fíle from the File menu; then select the 
source file from the dialog box. If the list of possible source files 
is disturbingly long, you can select Filter by Tíme in the File menu. 
When Filter by Time is on, only files that have been modífied since 
last assembled are displayed in the díalog box. 


As the assembly proceeds, the name of the current source file Is 
displayed in a box on the screen. Included files are displayed in 
parentheses; the number of parentheses indicates the level of nesting. 
Long file names may not fít entirely into the box. 
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Types of Source Files 


There ate two types of files that can be assembled: .Asm files and 
«Files files. .Asm files contain lines of source and the names of 
other files to be included into that assembly. When you assemble a 
.Àsm file, one .Rel file is produced. Here's a typical .Asm file: 


; File MyProgram. Asm 


XDEF Start , reference for Linker 


INCLUDE MacTraps.D ; use System Traps 
INCLUDE MyEquates .O ; use my Equates 


Start ; Start af code for Linker 


, This is where the sain body of code goes. 
. End of code for Assemble 





«Files files contain names of separate assemblies to be performed. 

When you assemble a .Files file, multiple .Rel files are produced. For 
example, if you change a value in a .D file that's used by three 
different library modules, you can reassemble all three modules using a 
file such as the following: 


; File Librory.Files 
Libi. Asm ; Lib1.Asa ---> Libi.Rel 


Lib2.Asm ; Lib2.Asm ---> Lib2. Rel 
Lib3.Asm ; Lib3.Rsm ---» Lib3 Rel 





In Search of Source Files 





The Assembler has a set of rules that determine where it looks for 
files to be assembled. These rules make use of the initial volume (the 
volume from which the Assembler was run) and the default volume (the 
volume that contains the file being assembled). They are as follows: 


- If the file name doesn't include a volume name, the Assembler 
tries to open the file first on the default volume, and then on 
the initial volume. If the file is not found, an error is 
reported. 


- If the file name includes a volume name, the Assembler tries to 
open the file first on the specified volume, next on the default 
volume, and finally on the initial volume. If the file is not 
found, an error is reported. 
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- In the two steps above, if the file name has no extension, the 
Assembler tries to open filename.Asm before searching the next 
volume. 


What the Assembler Produces 


The assembled product is placed in a .Rel file. This file contains 
relocatable code and symbol table information and must be linked by the 
Linker before an executable application is produced. 


If List to File is chosen from the Options menu, an assembled listing 
is placed in a .Lst file. If List to Display is chosen, the assembled 
listing is instead displayed on the screen. To temporarily stop the 
listing, hold down the Command key while you type an S. The cursor 
blinks while listing is suspended. To resume the listing, type 
Command-S again. 


To stop the assembly permanently, click on the Stop button or hold down 
the Command key and type a period (.). 


Errors encountered during assembly are written to a .Err file. 
Assembler errors are explained in an appendix. 





Assembler Syntax 


An Assembler source file consists of a series of lines of text, as 
entered in the Editor. These lines may be blank lines, comment lines, 
or instruction lines. 


Instruction lines contain some or all of the following: label, 


instruction (assembly-language or assembler directive), and comment 
fields. The following are valid instruction lines: 


EE kMDS2:Sampie instructions zem—————— 


Label MOVE *à, DO ; Comments are nice. 
Lone_label 
Indented_too: BSR Labe | ;, Indented labels have colons. 
AND D1,02 - Not all lines have labels... 


DC.B 'Hel!o' 
Et RTS ` Some have local labels 
84: BSR e 1 ; which may even be indented! 





The Assembler does not dístinguish between uppercase and lowercase, 
except within strings. 
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Labels 





If a label does not begin in column 1, it must be followed by a colon. 
The first character in a label must be a letter, a period (.), or an 
underscore ( ). Subsequent characters must be letters, numbers, 
periods, underscores, or dollar signs ($). Labels that are the same as 
directives or instructions are not allowed. 


The Assembler also supports local labels. A local label consists of an 
"at" symbol (@) followed by a decimal digit. If a local label is 
indented, it must be followed by a colon. 


The scope of a local label extends, in both directions, to the nearest 
non~local label. Any single local label can be used repeatedly within 
a file, but not within the scope of another instance of the same local 
label. 


Current Program Location 


The current program location is indicated by an asterisk (*). For 
example: 


BlkLen EQU BlkEnd-* ; Get length of following block 


Instructions 


An instruction can be a 68ØØØ instruction, an assembler directive, or a 
macro instruction. 68000 instructions are described in the 68000 
Reference Manual. Assembler directives and macro instructions are 
explained below. If the instruction requires an operand, at least one 
space or tab separates the instruction and the operand. 


Comments 





Except when it appears within a string (see below), a semicolon marks 
the beginning of a comment. The semicolon and the remainder of the 
line are ignored by the Assembler. In addítion, any line with an 
asterisk (*) in column 1 is treated as a comment. 


68090 Instruction Syntax 


The 68009 instructions and addressing modes are described in the 68000 
Reference Manual. The processor registers are named as follows: 


Dd..D7 Data Registers Ø through 7 

AQ ..A7 Address Registers Ø through 7 
A7 or SP Stack Pointer 

SR Status Register 


CCR Condition Code Register 
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PC Program Counter 


A group of address and data registers, used by the MOVEM command, is 
represented like this: 


Syntax Means 
DØ-D1 / A3 DØ, DL, and A3 


D2-D4/A1-A2/D7 D2, D3, Dá, Al, A2, and D7 


Any combination of individual data and address registers and ranges of 
data and address registers can be used, in any order. 


Addressing Modes 


The syntax of the addressing modes is shown below. The notation An 
refers to address register AP through A7; Dn refers to data register DØ 
through D7. Expressions, desígnated in the examples as Expr, are 
explained in the next section. 


Syntax Addressing mode 

Àn or Dn Register Direct 

(An) Register Indirect 

(An)+ Postincrement Register Indirect 

-( An) Predecrement Register Indirect 
Expr(An) Register Indirect with Offset 
Expr(An,An) Indexed Register Indirect with Offset 
Expr(An,Dn) Indexed Register Indirect with Offset 
Expr Absolute or Relative 

Expr(PC) Relative with Offset 

Expr(PC,An) Relative with Index and Offset 
Expr(PC,Dn) Relative with Index and Offset 
Expr(Dn) Relative with Index and Offset (see comment) 
#Expr Immediate 


Expr(Dn) is actually assembled as 
Expr-PC (PC,Dn) 


Both the sources and destinations of 68090 instructions use these 
addressing modes. The 68000 Reference Manual describes which 
addressing modes can be used with each instruction.  Expr(Dn) can be 
used wherever Expr(PC,Dn) is allowed. 
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Variants on 6800680 Instructions 


Many 68909 instructions can be performed on operands of different 
Sizes: byte, word, and long word. The 68000 Reference Manual lists 
the mnemonics for the 68900 instructions. To specify the length of the 
instruction, add the following extensions to the mnemonics: 


.B Operands are one byte long 
W Operands are one word long (2 bytes) 
SL Operands are long words (4 bytes) 
For example: MOVE.L  Test,AÓ : Move long word to Ag 


If you don't use a size extension, a default size is used (depending on 
the instruction). .B, .W, and .L are also used by the data allocation 
assembler dírectives described later in the chapter. 


Branch instructions have two forms: short and long. By default, the 
Assembler uses the long form. To specify a short branch, use the form: 


Bcc.S Short branch 


Jump instructions have two forms: word and long word. By default, the 
Assembler uses the word form. To specify a long jump, use the form: 


JMP.L Long jump 
Broad jumps are not allowed. 


You can also specify the length of the index register in the indexed 
addressing modes. By default, the low word of the register is used as 
an index. For example, to specify the length in relative with index 
mode, use one of the following forms: 


Expr( PC, Dn. L) 


Note: The lengths that are allowed with particular instructions varies 
from instruction to instruction. 


Code Optimization 


Some code alteration or optimization is performed by the Assembler. 
ADD and SUB are changed to ADDQ and SUBQ, respectively, if the source 
operands are immediate (#) and within the range 1-8. 


The following table shows how the Assembler resolves jumps and branches 
to labels in the same segment and to labels in another segment. 
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Instruction Same segment Different segment 
JMP Label JMP  offset(PC) JMP offset(A5) 

JSR Label JSR offset(PC) JSR offset (A5) 

BRA Label JMP offset(PC) JMP offset(A5) 

BRA.S Label BRA.S offset( PC) error 

BSR Label JSR offset(PC) JSR offser(A5) 

BSR.S Label BSR.S offset( PC) error 

Bec Label Bcc offset(PC) error 

Bec.5 Label Bec.S offset(PC) error 


When the destination is in another segment, the operation is performed 
as a positive offest to A5 (the location of the destination's jump 
table entry). 





Expressions 


Addressing modes and assembler dírectíves often use arithmetic and 
logical expressions. Numbers and strings, and symbols that represent 
numbers, stríngs, and relocatable addresses, can all be used ín 
expressions. 


Expressions are evaluated as 32-bit signed integers. 


Numbers 





Four types of numbers can be used in expressions: hexadecimal, 
decimal, octal, and binary. Here are examples: 


$3FØ Hexadecimal numbers are preceded by a $ 
2091 Decimal numbers are the default 

^765 Octal numbers are preceded by a ^ 
2118919811 Binary numbers are preceded by a % 


Strings 


A string is one or more ASCII characters enclosed in single quotes. To 
put a single quote in a string, use two consecutive single quotes. The 
exact format of a string that is allocated in memory is defined by the 
STRING_FORMAT directive. Refer to the STRING_FORMAT section for more 
details. Here are some sample strings: 


'HELLO' 
'don''t' 
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Symbols 


A symbol is a name for a string, number, relocatable address, or macro. 
Strings and numbers are assigned to symbols by EQU and SET directives. 
Symbols are relocatable if they are created as labels, or if equated or 
get to labels. Macro symbols are set by macro definition statements. 


The first character in a symbol must be a letter (A-Z, a-z), a period 
(.), or an underscore ( ). Subsequent characters may be letters, 


numbers (9-9), periods, underscores, and dollar signs ($). 


All characters in a symbol are significant. 


Operations 


An operation is an action taken on one or more values. There are 
arithmetic, shift, and logical operations. They are: 


Type Operation Operator Comment 
Arithmetic Addition + 
Subtraction - 
Multíplication * 
Division / Integer result 
Negation = 
Shift Shift Right >> Zeros shifted in 
Shift Left << Zeros shifted in 
Logical And & 
Or ! 


Only addition and subtraction can be used on relocatable values. 


Precedence 
Multiple operators within an expression are evaluated in this order: 
l. Operations within parentheses (innermost first) 
2. Negation 
3. Shift operations 
4. Logical operations 
5. Multiplication and division 
6. Addition and subtraction 


Operators of the same precedence in an expression are evaluated from 
left to right. 


Assembler Directives 35 


Assembler Directives 
The following directives are described in this section: 
Assembly Control Directives 

INCLUDE Include source file 


STRING FORMAT Set string format 
IF..ELSE..ENDIF Conditional assembly 


MAC RO Define a macro 

«MACRO Define a Lisa-style macro 
END End of source 

e DUMP Create a .Sym file 


Symbol Definition Directives 


EQU Assign a permanent value to a name 
SET Ássign a temporary value to a name 
REG Assign a register list to a name 

» TRAP Assign a name to a trap number 


Data Allocation Directives 


DC Define constant 

DS Define storage 

DCB Define constant block 

. ALIGN Align to word or long word boundary 


Linker Control Directives 


XDEF Defined externally 
XREF Referenced externally 
RESOURCE Begin resource type definition 


Printing Control Directives 


. NoList Turn off listing 

‚ListToFile Turn on listing to file 

«List ToDisp Turn on listing to the display 

+ Verbose Write information for Linker listing 

. NoVerbose Turn off information for Linker listing 


The printing control directives are self-explanatory. Refer to the 
Selecting Listing Options section, earlier in the chapter, for more 
details on normal and verbose assembly. 


In the descriptions below, the terms label, value, expressíon, and 
comment are used as defined earlier in the chapter. [Optional fields 
are enclosed in square brackets.] 
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Assembly Control Directives 


INCLUDE - Include Source File 
Format: [label] INCLUDE Filename [comment] 


INCLUDE is used to combine multiple source files in a single assembly. 
INCLUDE causes Filename or Filename.Asm to be used as the source file 
instead of the current fíle. When END is encountered in the file, 
assembly returns to the file in which the INCLUDE was used. Filename 
may contain a volume name. Here is a sample fíle that uses INCLUDE: 


XDEF Start : reference for Linker 


INCLUDE MacTraps.D ; use System Traps 
INCLUDE MyEquates.D ; use my Equates 


Start ; Start of code for Linker 


, This is where the main body of code goes. 


+ 





INCLUDE directives can be nested up to five levels deep. When an 
assembly is taking place, the name of the current input file is 
displayed. Included files are displayed in parentheses; the number of 
parentheses reflects the number of levels of nesting. 


STRING FORMAT - Set String Format 
Format: [label] STRING_FORMAT value 


This directive determines the format of the strings that the Assembler 
generates. 


Strings used as arguments to PEA or LEA instructions are allocated just 
after the code. If STRING_FORMAT is not used in the program, these 
strings are preceded by a length byte. Otherwise, bit @ of the last 
STRING FORMAT in the program determines the format of these strings. 
Use these values: 


STRING FORMAT = Ø Text followed by a @ byte 
STRING FORMAT = 1 Text preceded by a length byte 


Strings used as arguments to DC.B, DC, DC.W, and DC.L are allocated at 
the point at which they are defined. By default, they are written 
without trailing Ø bytes or leading length bytes. Bit 1 of 

STRING FORMAT is used to determine the format of these strings. Use 
these values: 
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STRING FORMAT = Ø Text with no length or trailing Ø byte 
STRING FORMAT = 2 Text preceded by a length byte 


With the DC.B directive, no padding of strings ever takes place. With 
the DC (word), DC.W, and DC.L directives, zeros are placed before the 

string to align the string to the nearest word boundary and at the end 
to fill to the nearest word or long word boundary. 


The format of both types of strings is set by each STRING FORMAT 
Statement used. For example, the statement 


STRING FORMAT = 3 


causes all strings to be preceded by a length byte. Here are some 
examples of the use of strings. The first two do not cause special 
string memory to be allocated; the next two do. 


Move ASCII 'JUNK' into DØ 

Use 'A'-'a' as a constant 

Push address of ‘NewString' 
'NewString' placed at end of code; 
form determined by STRING FORMAT 

Place string data in code 
using current STRING FORMAT 


MOVE #'JUNK',D@ 
SUB #'A'-'a',DØ 
PEA 'NewString' 


DC.L 'Try Again’ 


dor we MP we P we Bt 


IF..ELSE..ENDIF - Conditional Assembly 


Format: [1abel] IF condition [ comment ] 
[ELSE comment] 
ENDIF [comment] 


IF..ELSE..ENDIF are used to include or exclude sections of code at 
assembly time based on the value of a condition. 


IF specifies to the Assembler that the subsequent block of code should 
be assembled íf and only if the condition following IF is true. The 
block of code is terminated by an ELSE (if there is one), or an ENDIF. 
If ELSE is used, it specifies to the Assembler that the subsequent 
block of code should be assembled if and only if the condition 
following IF is false. An ELSE block is terminated ENDIF. 


A condition is true if it evaluates to a nonzero value; otherwise it is 
false. Two types of conditions can be used: expressions or the 
relationship between two expressions. Expressions cannot be 
relocatable.  Non-stríng expressions can be compared using >, <, >=, 
<=, =, and <>. Strings can be tested for equality using = and <>. 
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Conditionals can be nested. 


MACRO - Macintosh-Style Macros 


When your source is assembled, each macro call is replaced by the text 
(usually a list of instructions) defined as that macro. The parameters 
used ín the macro call are placed, character-for-character, at 
designated positions in the list of instructions. All characters 
except Return and comma (,) can be passed to a macro in the parameter 
list. 


Macros can be nested up to eíght levels deep. 
Here is the format of a Macintosh-style macro definition: 


Format: MACRO name [argument(s)] = 
macro body 


A macro definition is delimited by the MACRO directive and a vertical 
bar (|). It consists of a macro name, an optional list of arguments, 
followed by "=", and a macro body that makes use of those arguments. 


The macro body is simply text. This text is exactly like normal source 
text, but with one exception: Arguments, which are to be replaced by 
parameters specified in the macro call, are enclosed in braces (10). 


Each argument has a unique symbol within the macro. Multiple arguments 
are separated by commas, wíth no intervening spaces. 


For example: 


MACRO MODS R1,R2 = 
DIVS (R1), (R2) 
SWAP {R2} 


The macro MODS has two arguments, Rl and R2. It can be called, for 
example, with the macro call: 


MODS D1,D2 


When the program is assembled, this call causes the following 
instructions to be placed in the code: 


DIVS D1,D2 
SWAP D2 


Macro calls are not necessarily entire instructions; they can be used 
anywhere. The following example shows a macro that is used as part of 
an instruction: 


MACRO SegRef LabelName = {LabelName}(A5)| 
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SegRef can be used like this: 
LEA SegRef Label,AØ 

It causes the following instruction to be placed in the code: 
LEA Label(A5) , AØ 


It is possible for a macro to use just part of a string received as an 
argument. A partial argument is designated by following the argument 's 
name with |N:M where N is the position in the string of the first 
character to be used (Ø is the first position), and M is the number of 
characters to use. For example, if you define 


MACRO LAST2 STR = DC.B '{STR{2:2}'| 
Then using the macro 

LAST2 ABCD 
is equivalent to using the instruction 


DC.B 'CD' 


«MACRO .ENDM - Lisa-Style Macros 


Format: .MACRO name l[argument(s)] [comment] 
macro body 
. ENDM [comment ] 


A Lisa-style macro is delimited by the .MACRO and .ENDM directives. It 
consists of a macro name and a macro body that contains optíonal 
arguments. When the Assembler encounters the macro name, ít 
substitutes the macro body for the macro name in the assembly text. 
Wherever an argument, Xn, occurs in the macro body (n is a digit from i 
through 9), the text of the nth parameter is substituted. Null strings 
are substituted for omitted parameters. 


Here is a sample Lisa-style macro: 


«MACRO Help 

MOVE %1,D¢ ; get first parameter 

ADD DØ ,%2 ; and add it to second parameter 
«ENDM 


When this macro is called by the instruction 
Help Me , Rhonda 


The following text is assembled: 
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MOVE  Me,D@ 
ADD DØ , Rhonda 


END - End of Source 
Format: [label] END 


The end of a source file may optionally be indicated by an END 
directive. When END is used, all subsequent lines in the file are 
ignored by the Assembler. If END is omitted, the physical end of file 
indicates the end of a source file. 


«DUMP - Make .Sym File 


Format: [label] «DUMP Filename 
The .DUMP directive instructs the Assembler to create a symbol table 
(.Sym) file and to place it in the file named Filename.Sym. .Sym files 


are used by PackSyme to create packed symbol files, as explained at the 
end of the chapter. 


Symbol Definition Directives 


EQU - Assign Permanent Value 
Format : symbol EQU expression [comments] 
This directive assigns an expression to the specified symbol. The 
symbol cannot be redefined later in the program. The expression can be 
any valid operand in any addressing mode. It may contain undefined 
symbols, register references, and so on. For example, 

LookTable2 EQU Table2(Aß) 
is a legal form, as long as LookTable is always used in the proper 
context. The expression can't contain more than one undefined 
identifier. For example, although 

A EQU B 
is a valid statement, 


A EQU B-C 


is not. 
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SET — Assign Temporary Value 


Format: symbol SET expression [comments] 


Like EQU, this directive assigns a value to the specified symbol. 
However, the symbol can later be redefined by other SET directives. 
The expression is the same as an expression used with EQU, above. 


REG - Assign Register List 


Format: symbol REG register list [comments] 


This directive assigns a register list to the specified symbol. The 
register list represented by the symbol can then be used in the MOVEM 
command. The syntax of a register list is defined in the Assembler 
Syntax section of this chapter. 


«TRAP - Assign Name to Trap Number 
Format: [label ] «TRAP name SAxxx 


This directive assigns a name to the specified trap number so that the 
name can be subsequently used as a 68000 instruction. The name must be 
a valid symbol, and the trap number must have a corresponding entry in 
the trap díspatch table. This directive is primarily used in the 
system trap files. 


Data Allocation Directives 





All .Rel files created by the Assembler have two parts: the code area 
and the data area. Everything in a source fíle that produces a value 
is placed into the code area. Code areas are then loaded into the 
proper code segment by the Linker. Data areas defined by DS directives 
are combined into a global block. This block is located by the Linker 
downward from -5109(A5). 


This a good way to create permanent storage for handles. 
The starting address of the global block can be set using the /GLOBAL 


Linker dírective. 


DC - Define Constant 


Format: [label] DC.B value(s) [comment ] 
[label] DC value(s) [comment ] 
[label] DC.W value(s) [comment] 
[label] DC.L value(s) [comment ] 
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The DC directives place data in the code area of the program. These 
four forms of the DC directive generate data that is byte aligned 
(DC.B), word aligned (DC or DC.W), and long word siigned (DC.L). 


A value is an expression that evaluates to the data to be stored. 
Multiple values are separated by commas. 


With the DC.B directive, no padding of strings ever takes place. With 
the DC (word), DC.W, and DC.L directíves, zeros are placed before the 
string to align the string on a word boundary and at the end to fíll to 
the nearest word or long word boundary. The format of the string is 
determined by the STRING FORMAT directive. 


DS - Define Storage 


Format: [1abel] DS.B length [comment] 
[label] DS length {comment ] 
[label] DS.W length [comment ] 
[label] DS.L length [comment ] 


The DS directive is used to reserve memory locations. The length is an 
expression specifying the number of bytes, words, or long words to be 
reserved. The expression may not contain values that are not yet 
defined. 


These memory locations are always located relative to A5. When you 
reference a label defined using DS, you must explicitly reference ÅS. 
For example: 


DS.L MenuHandle s reserve handle space 
MOVE.L (SP)+,MenuHandle(AS) : get handle from stack 


Word alignment is enforced for DS (word), DS.W, and DS.L. Labels 
always refer to the first address in the defined area after alignment. 


DCB - Define Constant Block 


Format: [label] DCB.B length,value [comment] 
[1abel] DCB length,value [comment ] 
[label] DCB.W length,value [comment] 
[label] DCB.L length,value [comment] 


The DCB directive is used to reserve blocks of memory, at the current 
position in the program, that are to be {nitialized to a certain value. 
Length specifies the number of bytes (DCB.B), words (DCB or DCB.W), or 
long words (DCB.L) in the block. The expression specifying the length 
may not contain forward references. Value specifies the initial value 
of the storage units in the block; it may contain forward references. 


Word alignment is enforced for DCB, DCB.W, and DCB.L. Labels always 
refer to the first address in the defined area after alignment. 
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«ALIGN - Align to Word or Long Word Boundary 


Fornat: [label] «ALIGN value [comment ] 


This directive causes the proper number of bytes to be reserved such 
that the next statement is aligned on a byte, word, or long word. 


The value is an expression that determines the alignment, as shown 
below: 


value = 1 Align to byte boundary (No-op) 
value = 2 Align to word boundary 
value = 4 Align to long word boundary 


Linker Control Directives 


The XDEF and XREF directives should be used to specify all routines 
that are either used or defined externally. These directives allow 
independently assembled modules to share routines with one another. 


XDEF - External Definition 
Format : XDEF symbol(s) [comment ] 


XDEF tells the Assembler that the specified symbols, defined in the 
current module, are used externally. The Assembler then generates 
information that can be used by the Linker to share these symbols with 
other code modules. Modules that wish to use the symbol must use XREF 
to gain access to it. Multiple symbols are separated by commas. 


The label used as the starting label in a linker control file must 
always be referenced using XDEF. 


Only addresses that are referenced by XDEF are placed in the .Map file. 
Thus you should use XDEF for each routine or label that you wish to be 
symbolically displayed by MacDB. 


XREF - External Reference 
Format: XREF symbol(s) [comment ] 


XREF tells the Assembler that the specified symbols, used in the 
current module, are defined in other modules. A code module must use 
XDEF for each routine or label used by other modules. The Assembler 
then generates information that can be used by the Linker to connect 
the real symbols to the module. Multiple symbols are separated by 
commas. 


If you use XREF with a symbol that is also defined within the module, 
the Ássembler gives you a warning and allows the XREF. 
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RESOURCE - Begin Resource Type Definition 


Format: RESOURCE type ID [name [attr] |] 


The RESOURCE directive is explained in full detail in the chapter on 
the Linker. This directive should not be used in the main portion of 
your application; it should only be used in files that are linked after 
the /RESOURCES Linker directive. 


The type is an expression that should evaluate to a four-character 
string. It can be one of the standard resource types or a new type 
that you are defining. The resource ID is a nonrelocatable integer 
expression. The specified integer must be unique within the specified 
type. The optional name is a string that must be unique within that 
resource type. The attr field is a nonrelocatable integer that is used 
to specify the value of the resource's attribute byte. 


Note that the parameters are not separated by commas. 
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Creating Packed Symbol Files 


The PackSyms program lets you compress the symbols used by your program 
into a packed form. This packed symbol file can then be used as input 
to the Assembler. Using packed symbol files saves disk space and 
memory space, and makes assembly faster. 


The first step in generating a packed symbol file is to use the .DUMP 


assembler directive to place the application's symbols in a .Sym file. 
Here is a sample file that creates a .Sym file: 


; File MyEquates Asm 


INCLUDE SysEqu.D ;, You can INCLUDE packed files 


INCLUDE ToolEqu.D ' as well as text files to create 
INCLUDE MyEquates. Txt : one big packed symbol file. 

. DUMP MyEquates ; Now dump to MyEquates. Sym. 

END ; End of source. 


When assembled, this file generates the file MyEquates.Sym. .Sym files 
are text files that can be edited using the Editor. 


Once you have created a .Sym file, you are ready to run PackSyms. Its 
menu bar contains three menus: Transfer, File, and Options. First 
choose the display option you want from the Options menu. Next, choose 
Select Input from the File menu, and choose the .Sym file to be added 
to the packed symbol file. Repeat this step for each .Sym file to be 
added. When all desired .Sym files have been added, choose Select 
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Output from the File menu, and enter the name of the file to contain 
the packed symbol information. This file should have the extension .D. 


The new .D file can then be used in an Assembler input file. For 
example: 


MDS2:MyRpplication.fism EEE 


; Flle MyApplication.Asm 


INCLUDE MyEquates.D ; get packed symbols 
INCLUDE Modute1.Asm ; and code 

INCLUDE Module2.Rsm 

END ; end of assembly 





About Packed Symbol Files 


The Assembler identifies packed symbol files by type and not by 
extension. For example, you can use a text file name MyEquates.D 
during program development and replace it with a packed symbol file 
when the symbols stop changing.  Thís replacement is entirely 
transparent to the .Asm file, it speeds up assembly, and it frees up 
disk space. 


Chapter 4 


The Linker 
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About This Chapter 


This chapter describes the Linker, the program that takes .Rel files 
produced by the Assembler and connects them into an application. 


The first part of this chapter describes the Linker. The rest of the 
chapter describes the commands accepted by the Linker. 


Files Required 


If you wish to move the Linker to a different disk, you must move the 
file named Link. If you wish to transfer from the Linker to the 
Editor, the Assembler, the Executive, or RMaker, those applications 
must also be on the disk. 


File Naming Conventions 


«Link is the required extension for Linker control files. Linker 
control files are text-only files, as created by the Editor. 


.Map is the symbol table file, used primarily by MacDB. If 
a Linker listing was requested, it is also in this file. 


«LErr indicates a file that contains the errors encountered during 
the linking process. 


The executable object file (an application) formed by the Linker has no 
extension. 


The Structure of a Macintosh Application 


This section contains information from the Inside Macintosh chapter 
with the same name. Please refer to that chapter for more details. 


Macintosh files have two forks: a resource fork and a data fork. The 
resource fork contains a number of resources; the data fork may contain 
anything. The simplest application created by the Linker has two 
resources in the resource fork, and nothing in the data fork. The 
first resource is the 'CODE' resource with ID Ø. By definition, this 
resource contains the jump table and information about the 
application's use of parameter and global space. The second resource 
is the 'CODE' resource with ID l. It contains the application's first 
code segment. 


More complicated applications can be created using Linker commande, 
described below. With these commands, you can add code segments and 
other resources to the resource fork of the file, or you can place 
information in the data fork of the file. You can also set the 
directory information that specifies the file's type and creator. 
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Invoking the Linker 


There are several ways to invoke the Linker: 
- From the Finder, select and open the application named Link. 
- Choose Link from the Transfer option of another application. 


- Call Link from an Executive control file, as described in 
Chapter 5. 


The Linker Control File 


a REE EEE EE EE re 


The Linker is controlled by a Linker control file with the «Link 
extension. This file specifies the names of the files to be linked 
together, how the program should be segmented, listing options, and 
various parameters of the .Map file. 


Each command in a Linker control file must be on a separate line. 
Blank lines in the file are ignored. 


Linker Commands 


The following sections describe the commands that can be used in Linker 
control files. 


filename.Rel The next file to link is the file named filename.Rel. 
filename The next file to link is the file named filename.Rel. 
!label Make label the starting location for the program 


(may only be used once). If label is omitted, the 
program is assumed to begin with location 9 of the 
first file. You must use XDEF to make label 


external. 
< Start a new segment. 
[ Turn on code listing to .Map file. 
] Turn off code listing to .Map file. 
( Turn on lísting of local labels to .Map file. 
) Turn off listing of local labels to .Map file. 
$ End of Línker control fíle. 
/Verbose Turn on verbose linker output. This option turns 


on listíng of linked code. 
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/NoVerbose Turn off verbose linker output. 

/Undef OK Give warnings only for undefined symbols. 
/NoUndef Give fatal errors for undefined symbols. 

/Type Set type and creator bytes in file directory. 
/Bundle Set bundle bit in file directory. 

/Globals value Set the start of the global space to value(A5). 


/Output filename Specify the name of the output file. 
/Resources | Begin resource portion of application. 


/Data Begin data portion of application. 


Setting the File's Type and Creator 


Each file's directory contains eight bytes that specify the file's type 
('APPL', 'TEXT', and so on) and creator ('MPNT', 'EDIT', and so on), 
and a bít that specifíes to the Finder that the file uses the Bundle 
resource (type 'BNDL') descríbed in Inside Macintosh.  Àn applícation 
must have the type 'APPL' if it is to be launched by the Finder when 
you open it. An application's creator bytes should be the signature 
for that application. The creator bytes for a file that isn't an 
application should be the signature of the application to be launched 
when you open that fíle. 


For example, the Editor has the type 'APPL' and the creator 'EDIT', and 
documents created by the Editor have the type 'TEXT' and the creator 
'EDIT'. When you open the Editor or a document created by the Editor, 
the Editor is launched. 


(By the Way) 
Application sígnature bytes, and type bytes for other 
files, must be assigned (or approved) by Apple Technical 
Support. 


To use the /Type command, follow the command by two four-byte strings, 
as in 


/TYPE 'APPL' 'MYAP' 


If the creator string is omitted, it is set to 9. If this command is 
not used, the type is set to 'APPL'. When an error occurs during 
linking, the file is given the creator 'BADF'. This prevents it from 
being launched by the Finder. Type strings are case sensitive. 


To set the bundle bit in the file's directory entry, place the /Bundle 
command in your Linker source. 
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Setting the Global Storage Area 


Data storage allocated by the DS assembler directive is normally placed 
downward from -$1ØØ(AS). QuickDraw globals are placed in the area 
immediately below A5. The /Globals directive lets you change the 
address of the global storage area. For example, to place data at 
-$200(45) instead, use the directive: 


/Globals -$209 


The value used to specify the address must be negative. 


Specifying the Output File 


The /Output directive specifies to the Linker the name of the file in 
which it places its output. This file can be an application file, a 
resource file, or some other type of file. Note that /Output specifies 
the name of a single output file, regardless of its position in the 
Linker control file. 


An example of a Linker control file is given below. A more complex 
example is given later in the chapter. 


iStart ; starting location of the application 
/Dutput TestProgram , output file is TestProgram 

[ ; listing on (assemble w/verbose on) 
MyProgram , first file is MyProgram. Rei 


Parser , second file is Parser .Rel 
Dispatcher ; third file is Dispatcher .Rel 


; done linking... 





Adding Resources and Data to the Code 


The Linker provides directives that allow you to add resources to the 
resource fork and to place data in the data fork of the file. 
Alternately, you can use the Resource Compiler to generate the resource 
portion of your application, as explained in the chapter on RMaker. 


The code, resource, and data portions of an application must be given 
to the Linker separately, and in that order. The beginning of the 
resource portion ia indicated by the /Resources directive, and the 
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beginning of the data portion is indicated by the /Data directive. 
Here is a sample Linker control file that uses these directives to 
place some resources after the code in the resource fork of the file 
and to place data in the data fork of the file: 


: MDS2:Bi9.L ¡n= 


IStart ‚ starting location af the application 
] . listing off 


Codelodu e 1 - code modules are linked first 


Codelodule2 
< ‚ this module is a separate segment 


Codettodu | e3 


¿Resources : resource modules are linked next 
RsrcModule 1 
RsreModule2 


¿Data : data modules are linked last 


DataModule i 
$ ; done linking 





All files linked by the Linker must be .Rel files, as generated by the 
Assembler or RMaker. Resource .Rel files have a strictly defined 
format; data .Rel files can contain anything. 


Each resource in an Assembler source file should be initiated with the 
RESOURCE assembler directíve. The parameters are the resource type, 
the resource ID, an optíonal resource name, and an optional attríbute 
byte. For example, to begin a menu resource with an ID of 4 and no 
name, use the directive 


RESOURCE 'MENU' 4 


It's a good ídea to use a '.ALIGN 2' directive before the resource to 
avoid undesired paddíng bytes at the beginning of the resource. 


External symbols may not be defined in files linked following the 
/Resources directive. /Resources should be followed by the data 
contained in the resource. In the case of certain resources, such as 
'DRVR'! resources, the data in the resource is actually code. 


An effective way to define resources is to create a macro for each 
resource type. For example: 
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MACRO DEFINEMENU NAME,ID,FLAGS = 


. ALIGN 


RESOURCE 


DC .W 


2 

'MENU' {ID} 

(ID) :Menu ID 

SØ «Menu width 

S ;Menu height 

sg ¡Menu definition procedure 
{FLAGS} ;Enable flags 

(NAME) 


MACRO MENUITEM TEXT,ICON,KEY = 


DC.B 
DC.B 
DC.B 
DC.B 
p B 


(TEXT) 

{ICON} 

{KEY} 

NT ;Marking character 
$ë ;Style 


Then, when defining a menu, you could use calls such as the following: 


DEFINEMENU 'Transfer', Launch Menu ID+Edit_ID, $FFFFFFED 


MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM 


DC.B Ø 


'Edit', 
tt 
'Asm', 
'Link', 


'Exec', 


send of items 


Refer to Inside Macintosh for the formats of the different types of 


resources. 
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The Executive 
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About This Chapter 


This chapter describes the Executive, an application that accepts a 
text file as input, and uses the commands in the text file to launch 
other applications. 





Files Required 


If you wish to move the Executive to a different disk, you must move 
the file named Exec. If you wish to transfer from the Executive to the 
Linker, the Editor, the Assembler, or RMaker, those applications must 
also be on the disk. 





File Naming Conventions 


«Job is the required extension for Executive control files. Only 
files with this extension can be selected using the Open Job 
File option in Exec's File menu. 


Invoking the Executive 


There are several ways to invoke the Executive: 
- From the Finder, choose and open the application named Exec. 
- Choose Exec from the Transfer menu of another application. 


- Call Exec from an Executive control file. 


The Executive Control File 


The Executive is controlled by an Executive control file with the .Job 
extension. This file specifies the names of applications to be run and 
what to do when the applications finish. 


An Executive control file consists of a sequence of lines; each line 
invokes an application. A line consists of four fields: the 
application to be called, a string to be passed to the application as 
input (usually a filename), the application to be called if the 
original application is successfully completed (usually Exec), and the 
application to be called if an error occurs in the original 
application. Each field must be separated from the next by exactly one 
Tab character. 
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Here is a sample Executive control file: 


Asm Foo.Files Exec Edit 
Link Foo. Link Exec Edit 


It assembles the files specified in Foo.Files, and, if successful, 
links the files specified in Foo.Link. If either the assembly or the 
linking fails, the Editor is invoked, and the Exec terminates, but can 
be restarted or continued from the Execute menu. 


Using the Executive 


When you are using the Executive, all applications must be on the 
startup volume, which must not be write-protected. In addition, the 
volume containing the .Job file is established as the default volume 
for files used by the application. Use volume names for files that 
aren't on the same volume as the .Job file. 


The default name for the Exec file is Exec.Job; it must be on the 
startup volume. To use Exec.Job, choose the command Execute Exec.Job 
from the Execute menu. 


If you give your Exec file another name, you can place it on other 
volumes. Exec files must always have the extension .Job. To use a 
.Job file, select it using the Open Job File command in the File menu. 


If an error occurs while an Exec file is running, a temporary file is 
left on the disk. This file allows you to resume the Executive, 
presumably after correcting the error. If you choose Resume from the 
Execute menu, the Exec file starts at the line following the one in 
which the error occurred. If you choose Resume and Re-do Last, the 
Exec file starts at the line in which the error occurred. 


You can stop an Exec file by typing a period while holding down the 
Command key. 
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The MacDB Debugger 
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About This Chapter 


This chapter descríbes MacDB, an applicatíon that helps you debug 
Macintosh applications. MacDB provides sophisticated debugging 
capabilities at the machine-language level. Its features include 


- Multiple memory display windows. Memory can be displayed in 
multiple windows as characters, words, long words or strings, or 
it can be disassembled symbolically. System traps are displayed 
symbolically too. 


- Versatile memory address display. Addresses can be displayed in 
hexadecimal or as symbols, and you can use these symbols in 
expressions (for example, you can set the PC to START). 


- One or more register display windows. All registers and memory 
locations can be changed easily. 


- Multiple breakpoints can be set and cleared. 

- Instructions can be executed one at a tíme. 

- Memory search for patterns. 

- Special trace and break capability for system trap instructions. 
- Display and checking of the heap. 


- Display of linked lists. 
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Setting Up MacDB 


The use of MacDB requires two Macintoshes (or a Lisa running MacWorks 
and a Macintosh) that are connected together: The target machine runs 
the program to be debugged, and the debug machine runs MacDB. 


If you are using two Macintoshes, connect the two machines together 
using the cable supplied with the Development System. The debug 
machine must be connected at port B, the printer port. The target 
Macintosh can be connected at either port. 


If you are connecting a Macintosh to a Lisa, use a Macintosh 
ImageWriter cable. The debug machine must be connected at port B, the 
printer port. If the target machine is the Lisa, it too must be, 
connected at port B. The cable connections required by the Macintosh 
and the Lisa are shown in an appendix. 


Next, run one of the Nub applications on the target machine. Use 
MacNub A if the target Macintosh is connected by port A, and MacNub B 
if it is connected by port B. Use WorksNub if the program to be 
debugged is running on a Lisa under MacWorks. 
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Running a Nub installs and initializes a small program in the system 
heap of the target machine. Now run the application to be debugged. 


On the debug machine, run the MacDB application. 


It is helpful to actually run MacDB while you read the following 
sections. If you have two machines, you can try out MacDB by running 
the Window sample program application on the target machine. 


One useful technique is to make the Nub the target machine's startup 
application using the Set Startup command in the Finder's Special menu. 
This guarantees that the Nub is already there just in case your 
application bombs. 


Theory of Operation 


MacNub is a small program that runs in the system heap of the target 
machine. When run, it places itself in the system heap, puts pointers 
to itself in most of the hardware exception vectors in $9000 through 
SØØFF, then returns control to the Finder. It then remains dormant 
until one of "its" exceptions occurs. Here is the list of exceptions 
to which MacNub responds: 


Exception number Assignment 


2 Bus Error 

3 Address Error 

4 Illegal Instruction 
5 Zero Divide 

6 CHK Instruction 

7 TRAPV Instruction 

8 Privilege Violation 
9 


Trace 
1Ø Line 1Ø1Ø Emulator 
11 Line 1111 Emulator 
24 Spurious Interrupts 
28 Level 4 Interrupts 
29 Level 5 Interrupts 
39 Level 6 Interrupts 
3l Level 7 Interrupts 
46 Trap SE (breakpoints) 


68000 exception processing is described in the 68009 Reference Manual. 
The simplest way to generate an exception on the target machine is to 
press the interrupt button (the rear button on the programmer's 
switch). Another good technique is to place the line 

DC.W SFFG@1 ;generate a line SF exception 


at the beginning of your program, or wherever you want MacDB to first 
get control. (Actually any value $SFØØØ through SFFFF can be used.) 
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When one of these exception events occurs in the target machine, the 
Nub gets control and sends an interrupt to the debug machine. The 
debug machine (if running MacDB) displays a box that lets you select 
whether to Debug or Proceed. 


If you select Proceed, the target machine continues execution at the 
current value of the PC. If the PC points to an instruction that 
caused an exception (such as the $FFAl used above), the exception will 
happen again. You must manually advance the PC before selecting 
Proceed. 


If you choose Debug, MacDB requests from the target machine all the 
information necessary to update its windows. Normal operation of the 
target machine is suspended until you choose Proceed from the Run menu. 


The MacDB Windows 


Here is a typical MacDB display, and a brief description of the default 
contents of each of the windows. 


€ Debug Run Bkpts Window formet 5qmbots 


pC Registers WIE 
nmm 


PC 

PSTART JSR $34C(PC) mE 

START +4 JSR $4ECPC? DON AO0AB 

START +8. JSR $56<PC) FFFF 0000 

STRRT*C: Dr awtenu&an 5001 0024 

START+E. JSR $96<FC > 0000 0024 

START +12: JSR $9ECPC > 0000 OOFF 

START + 15: 0000 FFFF 

START+ IA: TE Idle FFFF FFG3 
STAAT+IC ` Sys temTask 
STRRT* IE: CLR -<A?> 
STRRT *20 

STRRT*24: PER $2EE<PC > 
START +28: GetNex tEvent 
+START+ZR: MOVE (A7 34, DO 
START+*2C : SEQ S *$-18 
START+2E JSA $9C(PC > 
STAAT+32 BEQ S *$- 1E 
START +34 RTS 

IN| THAMAGERS PEA $-4(A5) 
INITMANA+4 InıtGraf 

INI THRNA*6. Ini tFont 


INITHANA+9: MOVE L 2$FFFF DO Breskpoints 


INITMANA+E: FlushEventis SSE ee Ui 


INI TMANAt 10: Ini ti ndow 4 | — 
INETANA+ 12: Ini thenus er "STARAT+ZA: ua 


0001 R6D4 





- The PC window displays memory starting at the current value of the 
program counter (PC). The value of the PC is indicated by the 
"at" symbol (@) to the left of the first address displayed. 
Addresses at which breaks have been set are marked by asterisks 
(*). By default, memory in the PC window is displayed as 
disassembled instructions. In this example, a .Map file has been 
loaded to provide symbolic display of addresses. The program 
counter is set to START, and a break is set at START+2A. 


- The Registers window displays the values of the registers. 
Although not visible in this example, the previous value of a 
changed register is displayed in brackets ([]) to the right of the 
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current value. In the example, the DØ "cell" is selected to be 
changed. Cells are described below. 


The upper Examine window displays the contents of the stack in 
long word format. The display of this window is "anchored" to A7. 
This is indicated by the anchor symbol and the seven in the upper 
right of the window. The '7>' to the left of the first address in 
this window shows that address register 7 points to this address. 


The lower Examine window is not anchored to a specific register. 
The window happens to contain the addresses contained in AQ and 
A5. 


The Breakpoints window displays the addresses at which breakpoints 
are set. In the example, there is a breakpoint set at address 
START+2A. 


Features of MacDB Windows 





MacDB windows behave much like most Macintosh windows; however, they 
have a few unique features. 





Close Box 
Start Box 
Anchor Bax 
Title Bar 
Align Box 
Scroll Arrow 


Scroll Bar 
Scroll Box 


Scroll Arrow 
Size Box 


The active window in a Macintosh application is the window with the 
highlighted title bar. As with other applications, there is only one 
active window at a time; however, unlike most others, it is not 
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necessary to select a window before selecting something within the 
window: A single click activates the window and performs an action. 
For example, if you click on a scroll arrow in an inactive window, the 
window becomes active and scrolls. 


The Close Box 


The close box is used to remove a window from the screen. The original 
PC, Registers, and Breakpoints windows cannot be closed. Duplicates of 
windows, made with the Duplicate command in the Window menu, can all be 
closed. 


The Title Bar 


The title bar is used to drag the window around on the screen. To 
change a window's title, use the Title command in the Window menu. 


The Start Box 


The start box, the grey region below the title, is used to set the 
address of the first location displayed in the window. For example, if 
you click on the value shown for the PC in the Registers window and 
then click on the start box of an Examine window, the window is updated 
to display memory starting at the current value of the PC. The 
selecting of values within windows is discussed below in the section on 
cells. 


The Anchor Box 


The anchor box, to the right of the start box, displays the number of 
the register, if any, to which that window is anchored. For example, 
the upper Examine window is by default anchored to A7, indicated by the 
anchor and the 7 in the anchor box. Whenever this window is updated, 
the address contained in A7 is the first address displayed. Note that 
the 7 could mean A7 or D7. 


Anchors are set and cleared using the Anchor and No Anchor commands in 
the Window menu. They cannot be set for Register or Breakpoints 
windows. 


The Align Box 


It is not always possible for MacDB to determine whether memory data, 
such as dísassembled instructions, should be aligned on word or long 
word boundaries. When you click the: align box, just above the upper 
scroll arrow, the startíng address of the window decreases by one word. 
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The Scroll Arrows 


The scroll arrows work in the usual manner. Clicking a scroll arrow 
causes the window to scroll one line in the indicated direction. 
Scrolling continues until the mouse button is released. 


The Scroll Bar 


Clicking the scroll bar, either above or below the scroll box, causes 
the next windowful of memory addresses to be displayed. Clicking 
repeatedly on the scroll bar is considerably faster than scrolling line 
by line, and you still see every address in the displayed range. 


The Scroll Box 


The scroll box works in the usual manner. Because there are many 
memory addresses, it is a very good tool for moving quickly through 
memory, but a fairly poor one for finding a specific address. 


The Size Box 


The size box works in the usual manner. It is used for increasing or 
decreasing the size of the window either horizontally or vertically. 


Values in Cells 


Most of the things that appear within windows are addresses or values. 
As such they are useful as input to various MacDB calls described 
below. All addresses and values can be selected by clicking on them. 
When a cell is selected, it is inverted on the screen. Only one cell 
can be selected at a time. 


Changing the Value in a Cell 


To change the value in a register or memory cell in the target machine, 
just select the value to be changed and then enter a new value or 
expression. A box appears to let you cancel or accept the new value. 


Expressions can contain hexadecimal values, the operators + - * /, and 
symbols that are currently defined (as explained below). Hexadecimal 
values must be preceded by $ if they might be confused with symbols. 
The operators * and / are of equal and higher precedence than the 
operators + and -, which are also of equal precedence. 


Most address cells can be selected, but not changed. The first address 
cell in a window can be changed. 
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Handy Hints 


You'll find while debugging that the disk drive does not stop spinning. 
If you execute an infinite loop, the system will realize that the disk 
isn't in use, and it will turn the drive off. Try entering and running 
the instruction S60FE (BRA *-2). Return control to MacDB by pressing 
the interrupt button on the programmer's switch. 


Another useful technique is to no-op out undesirable instructions. The 
opcode for a no-op is $4E71. 
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Debug Menu 


128K/512K Mac 


This message tells you the amount of RAM ín the target (the other) 
machine. 


Heap Check On/Off 


Select this command if you wish the validity of the heap to be checked 
after each command executed by MacDB. If the command is selected, and 
errors are found in the heap, the range of addresses containing the 
fault is displayed in a box. 


Wait 
Wait instructs MacDB to wait for an interrupt from the target 


Macintosh. Execution of the target program does not resume if it was 
previously halted (see the Proceed command, below). 


Quit 


Quit leaves MacDB and restarts the Finder. 


Trace causes MacDB to execute the instruction that is currently j 
indicated by the PC. Once the instruction has completed, control 
returns to MacDB and all the windows are updated. 


System Craps are Created ag a Single instruction, If you wish to trace 
f 


the execution of a SyStem trap, use the Trace Into ROM instruction, b 
described below, 

b 
Proceed 4 
Proceed causeg execution of the Program to resume where it was 
interrupted. This normally allows the program to continue ag though 1t i 
had not been interrupted. If the Pc Still points to the instruction 
that caused the exception, you mugt manually advance the Pc, 

, 
Normal execution cannot be resumed if the interrupt was Caused by a Bus 
Error or an Address Error. , 
Go Till i 


Go To 


Go To causes execution to begin at the specified address, Control 
returns to MacDB when a breakpoint or some other exception occurs, 


Trace Into ROM 
EO RUM 


The Trace Into ROM command is usually dimmed. When the Pc indicates a 
system trap, Trace Into ROM is enabled. If you choose Trace Into ROM, 
MacDB dispatchea the call and returns with the Pc pointing to the first 
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Bkpts Menu 


When you set a breakpoint, MacDB saves the instruction at the 
breakpoint address and replaces it with a TRAP #$E instruction. When 
this address is executed, the exception caused by the TRAP instruction 
gives control to the Nub, which then calls MacDB. The instruction that 
was originally at that address is not executed. 


Because breakpoints are implemented by altering memory locations, they 
cannot be set in ROM. No warning is given if you try to set a 
breakpoint in ROM. 


The presence of a breakpoint is indicated in two ways: Its address is 
displayed in the Breakpoints window, and any occurrence of an address 
that contains a breakpoint, in any window, is marked by an asterisk. 
If the PC is at an address that contains a breakpoint, the PC symbol 
(@) is displayed instead. 


Set 
This command sets a breakpoint at the indicated address. The address 


is added to the Breakpoints window, and all references to that address 
in other windows are marked with an asterisk. 


Clear 

This command removes the breakpoint at the indicated address, if there 
is one. The address is removed from the Breakpoints window, and all 
references to that address in other windows are unmarked. 


Clear All 


This command clears all currently defined breakpoints. 


Window Menu 





New 


New creates a new Examine window and places it on the screen. It is 
useful if you want to look at several parts of memory at the same time. 


Duplicate 


This command makes a copy of the active window. All settings of the 
original window are duplicated. A duplicate window always has a close 
box. 
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This feature is particularly useful if you want to freeze a copy of a 
window for comparison with another (see Frozen/Thawed, below). 


Symbolic/Hex Address 


These two commands determine the format of the addresses displayed in 
the active window. Symbolic addresses can only be displayed if one or 
more .Map files have been opened (see the Open command in the Symbols 
menu). In this mode, addresses are displayed as offsets from the 
nearest defined label. 


When Hex Address is selected, all addresses are displayed in 
Hexadecimal. 


This command does not affect the symbolic display of system traps. 


Frozen/ Thawed 


This command allows the active window to be "frozen" for future 
reference and comparison with unfrozen windows. A frozen window has a 
thick black line as its left border. 


Although a frozen window may be moved about on the screen, and the data 
in the target machine may change, the contents of its window will not 
change until it is thawed (or closed). 


Anchor/No Anchor 


The Anchor command lets you "anchor" the addresses displayed in a 
window to one of the registers. The first address displayed in an 
anchored window is the contents of the register to which it is 
anchored. The register to which a window is anchored is denoted by an 
anchor symbol followed by a register number in the window's anchor box 
(see preceding figure}. 


A window may be anchored to any register displayed in the Registers 
window with the exception of SR. 
Title 


This command allows you to change a window's title. 
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Format Menu 





The Format menu allows you to select the format of the information 
displayed in the active window. You can select the format of each 
window except the Registers window. 


Inst 


This command causes the data in the active window to be displayed as 
machine-language instructions. Useful effective addresses are 
displayed to the right of the instructions. If a .Map file has been 
loaded, effective addresses are displayed symbolically. 


MacDB cannot always tell if instructions should be disassembled 
starting on a word or long word boundary. If you click on the align 
box, just above the upper scroll arrow, the starting address of the 
window is decreased by two. 


Char 


This command causes the data in the active window to be displayed as 
hexadecimal bytes. The ASCII character corresponding to each byte is 
displayed in brackets to the right of the value. If the value's ASCII 
character is not printable, a period is displayed. 


Word 


This command causes the data in the active window to be displayed as a 
sequence of hexadecimal words. To the right of each word is its ASCII 
representation. If a byte is not a printable ASCII character, a period 
is displayed. 


Long 


This command causes the data in the active window to be displayed as a 
sequence of long words. To the right of each long word is its ASCII 
representation. If a byte is not a printable ASCII character, a period 
is displayed. If the long word is the address of a defined symbol, the 
symbol 1s displayed to the right of the ASCII representation. 


Pascal String 


This command causes the data in the active window to be displayed as a 
sequence of Pascal strings (a length byte followed by a string). The 
first byte in the window is assumed to be a length byte. Subsequent 
characters are displayed until that many characters have been 
displayed, or until an invalid character is found. The next byte is 
then assumed to be a length byte. 
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List 


This command attempts to display the active window as a linked list. 
The first line in the window reads 


Offset = nnnn nnnn 


nnnn nnnn is the offset into the record where the link to the next 
record is found. To change the offset, just select the current offset 
value and type in a new value. 


The starting address of the window is the fírst byte of the first 
record.  Às many consecutive bytes of the record as will fit across the 
window are displayed. The offset is then added to the address of that 
line, and the contents of the calculated address is the starting 
address of the second record, which is displayed on the next line in 
the window. Records are displayed until the window is full, or until 
an invalid pointer is found. 


If all the records do not fit in the window, you can scroll downward to 
see subsequent records. You cannot scroll upward ín the window. To 
move upward, you can reselect the starting address for the window. 


Search 


Search allows you to search memory fot occurrences of a specified 
pattern within a specified range of memory addresses. When you choose 
the command, you are allowed to set the start address of the search, 
the end address of the search, a mask value, and a value. 


Each address in the memory range is logically ANDed with the mask and 
then compared with the specified value. If they match, then that 
address and its contents are displayed. 


If all the matching patterns do not fit within the window, you can 
scroll downward to see subsequent occurrences of the pattern. You 
cannot scroll upward in a Search window. To move upwards, you can 
enter a new start address, or you can select an address elsewhere on 
the screen, and then click in the start box, just below the window's 
title. 


. You can use the mask to set the síze of the pattern you are looking 
for. To search for a specific byte, set the mask to SFF. To search 
for a specific word, set the mask to SFFFF. To search for a long word, 
set the mask to SFFFFFFFF. 


À- Traps 


This command lets you monitor the execution of system traps ín the 
target application. Four lines appear at the top of the window. These 
let you set the range of traps to be monitored, whether a break should 
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occur when a trap in the range is encountered, and whether the trap 
monitor feature is currentiy active. 


Trap numbers are in the range $AØØØ through SAFFF. Set first to 
indicate the lowest trap number to be monitored. Set last to indicate 
the highest trap number to be monitored. If first is equal to last, 
just that single trap is monitored. If you wish a break to occur when 
a trap in the specified range is encountered, set the Break option to 
True (by clicking on False). The setting of the auto-pop bit in the 
monitored traps is ignored. 


If you wish to temporarily disable the monitoring of traps, set Enable 
to False by clicking on True. 


Once all your settings are correct, choose Proceed in the Run menu. 
This allows the target program to execute, but all traps in the desired 
range are displayed within the window. If the Break option is set to 
true, then control returns to MacDB when each trap in the range is 
encountered (before it is executed). 


Note that you can have multiple windows each monitoring a different 
range of trap instructions. 


Clicking Debug interrupts the target machine at the next trap. 


MemBlock 


This display format allows you to examine memory blocks within a heap 
zone. When you choose this command, the starting address of the window 
is automatically set to the first memory block in the current heap zone 
(immediately following the zone header). 


Each line in the window displays an eight-byte memory block header, 
enclosed in square brackets, followed by as much of the memory block as 
will fit across the window. In the case of nonrelocatable blocks, the 
memory block immediately follows the header in memory. In the case of 
relocatable blocks, the second long word in the header is a pointer to 
the block's master pointer. Such pointers are preceded by asterisks. 


Subsequent lines in the window display the headers for subsequent 
memory blocks. You can scroll up and down through heap zones. 


Symbols Menu 


This menu is used to assign symbols to memory addresses and to clear 
such assignments. Symbols are stored in .Map fíles. 
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Value 


Value lets you discover a symbol's value or a value's symbol. Either 
select an address in memory or a symbol before choosing the command, or 
be prepared to enter an address or symbol after choosing this command. 
It will display the symbol and its value. 


If there ia no .Map file loaded, or the specified address is outside of 
the program space, the value is displayed in hexadecimal. 


Open and Purge 


These commands let you control the display of symbols in MacDB. 


Each window (except Registers) can have a set of symbols assigned to 
it. When you first Open a .Map file, the symbols in the .Map file are 
assigned to all windows. These windows are treated as a group; opening 
a -Map file for any of them assigns new symbols to all of then. 


Purge clears the symbols assigned to the selected window and removes 
that window from the group. If you Open a .Map file with a purged 
window selected, the symbols are assigned to that window; it does not 
affect the symbols in other windows. 


MacDB is able to keep track of the symbols used by multiple segments, 
but they are bound to the segments that are in memory when the .Map 
file was opened. You must open the .Map file again if the loaded 
segments change. 


About Symbols 


When you start up MacDB, only trap symbols are displayed. 


When you open a .Map file, the symbols in the .Map file are read into 
memory. Only symbols that were referenced using the XDEF directive are 
placed into a .Map file. 


If you want to use equates that are not addresses, you must use a trick 
to get them into a form that MacDB recognizes. Each entry in a .Sym 
file looks like this: 

LABEL $48 $xxxxxxxx 
and each entry in a .Map file looks like this: 

LABEL= s:XXXXXXXX 
in which s is the segment number, and xxxxxxxx is the value. Thus if 
you change all instances of the string ' $88 $' in a .Sym file to 


t= Q:', and save it as a .Map file, the file can be opened and used by 
MacDB. 
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The MacsBug Debuggers 
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About This Chapter 
This chapter describes the MacsBug family of debuggers. 


The first part of the chapter describes the various versions of MacsBug 
and how they work. The next part of the chapter describes the syntax 
of commands accepted by MacsBug. The end of the chapter describes the 
commands themselves. 





About MacsBug 


MacsBug is a line-oriented single-Macintosh debugger. It shares memory 
with the application being debugged, thus MacsBug may not fit in memory 
with very large applications. 

The features of MacsBug include 


- The ability to display and set memory and registers. 


The ability to disassemble memory. 


Stepping and tracing through both RAM and ROM. 


Monitoring of system traps. 
- Display and checking of the system and application heaps. 


MacsBug gets control when certain 68000 exceptions occur. You can then 
examine memory, trace through the application, or set up break 
conditions and execute the application until those conditions occur. 


A i i Áá————————— 
Setting Up Mac s Bug 


MacsBug is not selected like a normal application. If there is a file 
named MacsBug on the startup disk when the system is turned on or 
restarted, MacsBug is installed into the system, and the message 
"MacsBug installed" is displayed right below "Welcome to Macintosh". 
The startup application 1s then launched as usual. To use a particular 
version of MacsBug, place it on a startup disk and name it MacsBug. 


MacsBug is placed in memory just below the main screen buffer. The 
amount of memory required by MacsBug depends on the version in use. 


Five versions of MacsBug are included in the Macintosh 68000 
Development System. They are described below. 
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Macs Bug 


This version of MacsBug runs on a 128K Macintosh. When invoked, it 
saves part of the screen and provides ten lines of debugging display. 
When exited, it restores the screen. 


MacsBug uses about 18K of memory. It will not run under MacWorks. 


Max Bug 


This version of MacsBug should be used on 512K Macintoshes. When 
invoked, it saves almost the entire screen and provides a 4-line 
display. When exited, it restores the screen. This version of MacsBug 
displays trap names instead of trap numbers. 


MaxBug uses about 4@K of memory. It will not run under MacWorks. 


TermBugA and TermBugB 


These versions of MacsBug send display information to an external 
terminal rather than to the Macintosh screen. TermBugA should be used 
if the terminal is connected to the modem port, and TermBugB should be 
used if the terminal is connected to the printer port. 


Communication over the serial ports is at 9609 baud, 8 data bits, 2 
stop bits, no parity bits, using the XOn/XOff protocol. 


TermBugA aud TermBugB use about 12K of memory. They will not run under 
MacWorks. 


LisaBug 


LisaBug is functionally equivalent to MaxBug. You should use it when 
you are using a Lisa running MacWorks. LisaBug will not run on a 
Macintosh. 


Theory of Operation 


When installed, MacsBug puts pointers to itself in many of the hardware 
exception vectors in addresses $0009 through SØØFF. It then remains 
dormant until one of "its" exceptions occurs. Here is the list of 
exceptions to which MacsBug responds: 


Exception number Assignment 
2 Bus Error 
3 Address Error 
4 Illegal Instruction 
5 Zero Divide 
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6 CHK Instruction 

7 TRAPV Instruction 

9 Trace 

19 Line 191% Emulator 

ll Line 1111 Emulator 
28 Level 4 Interrupts (not with LisaBug) 
29 Level 5 Interrupts (not with LisaBug) 
39 Level 6 Interrupts (not with LisaBug) 
31 Level 7 Interrupts 
47 Trap $F Instruction 


68009 exception processing is described in the 68000 Reference Manual. 


Invoking MacsBug 


The simplest way to generate an exception is to press the interrupt 
button (the rear button on the programmer's switch). When you are 
using LisaBug, press '-' on the numeric keypad. 


Another way to generate an exception is to add a line such as 
DC.W SFFØL ; generate a line 1111 exception 


at the point in your program where you want MacsBug to first get 
control. (Actually any value $FØØØ through $FFFF can be used.) 


Another good technique is to place the system trap 
_Debugger ; invoke system trap SA9FF 


into your program at che point where you want MacsBug to get control. 
This trap is defined in the file ToolTraps.Txt (and MacTraps.D). 


In addition, you can invoke system trap $ABFF. This trap is designed 
for use with the Lisa Workshop development system; it's explained at 
the end of the chapter. f 

When MacsBug gets control, it disassembles the instruction indicated by 
the PC and displays the contents of the registers. If the exception 
was caused by an SFxxx, SA9FF, or $ABFF instruction, MacsBug displays 
the message 'USERBRK', advances the PC to the next instruction, and 
then disassembles the instruction and displays the registers. 


It then displays the greater-than symbol (>) as a prompt, indicating 
that it is ready to accept a command. 


MacsBug, MaxBug, and LisaBug replace part of the screen with the 
debugging display. To see the application screen while the debugger is 
active, press the tilde/opening quote key in the upper left of the 
keyboard. To restore the debugger's display, press any character key. 
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Syntax of MacsBug Commands 


Commands consist of one or two command characters followed by a list of 
zero or more parameters (depending on the command). Parameters can be 
numbers, text literals, symbols, or simple expressions. 


Numbers 


Numbers can be entered in decimal or hexadecimal notation. Decimal 
numbers are preceded by an ampersand (&) and hexadecimal numbers are 
optionally preceded by a dollar sign ($). Numbers may be signed (+ or 
-); if they are, the sign should precede the notation symbol. Here are 
some numbers in several different formats. The formats shown are the 
same ag those displayed by the Convert command (described below). 


Number Unsigned Hex Signed Hex Decimal 
$FF $009099FF $000999 FF &255 
-$FF $FFFFFFØL -$9009009FF -6255 
&190 $09009964 $8009009064 &109 
+19 500000919 $09909919 &16 


Text Literals 


A text literal is a one- to four-character ASCII string bracketed by 
single quotes ('). If a string is longer than four characters, only 
the first four characters are used. When used by MacsBug, text 

literals are right justified in a long word. Here are some examples: 


String Stored as 
'A" 59090904 1 
'Fred' $46726564 
11234" $31323334 


Symbols 


Symbols are generally used to represent the registers. The symbols are 


RAY through RA? Address registers A@ through A7 
RDG through RD? Data registers DÓ through D7 

PC Program counter 

š Last address referenced ("Dot") 


TP Current QuickDraw port (thePort) 
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Expressions 


Expressions are formed by operators acting on numbers, text literals, 
and symbols. The operators are 


E addition (infix), assertion (prefix) 
- subtraction (infix), negation (prefix) 
@ indirection (prefix) 


The indirection operator uses the long integer at the location pointed 
to by the operand. Here are some valid expressions: 


RA7 +4 

1A7060-G10C 

TP+&24 
-RAØ+RA1-' FRED '+Q04C5Ø 


MacsBug Commands 


MacsBug commands can be divided into six groups: memory, register, 
control, A-Trap, heap zone, disassembly, and other miscellaneous 
commands. 


Å Return character repeats the last command, unless specified otherwise 
in the descriptions below. 


Parameters are represented by descriptive words and abbreviations such 


as 'ADDRESS', 'NUMBER', and 'EXPR'. All parameters can be entered as 
expressions. 


Memory Commands 


DM ADDRESS NUMBER (Display Memory) 

Displays NUMBER bytes of memory starting at ADDRESS, 

NUMBER is rounded up to the nearest 16 bytes. If NUMBER is omitted, 16 
bytes are displayed. If ADDRESS and NUMBER are omitted, the next 16 
bytes are displayed. 

Subsequent presses of the Return key display the next NUMBER bytes. 

The dot symbol is set to ADDRESS. 

If NUMBER is set to certain four character strings, memory is instead 
symbolically displayed as a data structure that begins at ADDRESS. The 


strings and the data structures they represent are 


"IOPB' Input/Output Parameter Block for File I/O 
'"WIND' Window Record 
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"TERC' TextEdit Record 
Refer to Inside Macintosh for a description of these data structures. 
You can prematurely terminate a DM command by pressing the Backspace 
key. 
SM ADDRESS EXPR] ++ EXPRN (Set Memory) 
Places the specified values, EXPRI through EXPRN, into memory starting 
at ADDRESS. The size of each value depends on the "width" of each 
expression. 
The width of a decimal or hexadecimal value is the smallest number of 
bytes that holds the specified value (four-byte maximum). Text 
literals are from one to four bytes long; extra characters are ignored. 
Indirect values are always four bytes long. The width of an expression 


is equal to the width of the widest of its operands. 


The dot symbol is set to ADDRESS. 


Register Commands 


Dn EXPR (Data Register) 


Displays or sets data register n. If EXPR is omitted, the register is 
displayed. Otherwise, the register is set to EXPR. 


An EXPR (Address Register) 


j 
Displays or sets ADDRESS register n. If EXPR is omitted, the register 
is displayed. Otherwise, the register is set to EXPR. 


PC EXPR (Program Counter) 


Displays or sets the program counter. If EXPR is omitted, the program 
counter is displayed. Otherwise, the PC is set to EXPR. 


SR EXPR (Status Register) 


Displays or sets the status register. If EXPR is omitted, the status 
register is displayed. Otherwise the status register is set. 


TD (Total Display) 


Displays all registers. 
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Control Commands 


BR ADDRESS COUNT (Break) 

Sets a breakpoint at ADDRESS. COUNT is the number of times that the 
breakpoint should be executed before breaking. If COUNT is omitted, 
the program is stopped the first time the breakpoint is hit. If 
ADDRESS is omitted, all breakpoints and current counts are displayed. 


A maximum of 8 different breakpoints can be set. 


CL ADDRESS (Clear) 

Clears the breakpoint at ADDRESS. If ADDRESS is omitted, ali 
breakpoints are cleared. 

G ADDRESS . (Go) 

Executes instructions starting at ADDRESS. If ADDRESS is omitted, 
execution begins at the address índicated by the program counter. 
Control does not return to MacsBug until an exception occurs. 

GT ADDRESS (Go T111) 

Sets a one-time breakpoint at ADDRESS, then executes instructions 
starting at ADDRESS. This breakpoint is automatically cleared after it 
T (Trace) 

Traces through one instruction. Traps are treated as single 
instructions. 

S NUMBER (Step) 

Steps through NUMBER instructions. If NUMBER is omitted, just one 
instruction is executed. Traps are not considered to be single 
instructions. 

SS ADDRESS1 ADDRESS2 (Step Spy) 

Calculates a checksum for the specified memory range, then does a Go. 
It then checks the checksum before each instruction is executed, and 


breaks into MacsBug if the checksum doesn't match. If ADDRESS! and 
ADDRESS2 are omitted, this feature is turned off. 
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ST ADDRESS (Step Till) 


Steps through instructions until ADDRESS is encountered. Unlike Go 
Till, this command does not set a breakpoint. Thus it can be used to 
step through, and stop ín, ROM. 


MR NUMBER (Magic Return) 


When debugging, you generally trace through a program one instruction 
at a time. MR lets you trace through to the end of a routine instead. 


When you use MR, it replaces the return address that is NUMBER bytes 
down in the stack with an address within MacsBug; then it does a Go 
(described above). The RTS that would have used that address returns 
to MacsBug instead of the caller. MacsBug restores the original return 
address, and then executes the RTS as if called by the Trace command. 
The prompt is then displayed, ready to trace the instruction after RTS. 


The usual way to use this routine is to trace until just after a JSR 
(return address Ø bytes down in the stack), and then do an MR (Ü is the 
default NUMBER). The rest of the routíne is executed, and control 
returns to MacsBug. 


This command isn't repeated when you press Return; a Trace command is 
executed instead. 


RB (Reboot) 


Reboots the system. 


ES (Exit to Shell) 


Invokes the trap ExitToShell, which causes the startup application to 
be launched. 


A-Trap Commands 


The A-Trap commands are used to monitor "1919 emulator" traps. These 
commands use up to six parameters (TRAP1, TRAP2, ADDRESS], ADDRESS2, 
Di, and D2) that specify which traps and other conditions should be 
monitored. If no parameters are given, all traps are monitored. 


TRAP] and TRAP2 specify the range of the traps. Operating System traps 
are in the range Ø through 255; Toolbox traps are between 255 and 511. 
If only TRAP1 is specified, the command is invoked for trap TRAPl. If 
TRAP! and TRAP2 are specified, the command is invoked for all traps in 
the range TRAP] through TRAP2. ADDRESS] and ADDRESS2 specify the range 
of calling addresses within which traps should be monitored. Finally, 
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Dl and D2 specify the values of data register Ø within which traps 
should be monitored. 


These commands set up conditions for the monitoring of traps. You 
generally use the Go command Immediately after a trap command to await 
the use of a specified trap. When a trap in the indicated range is 
encountered appropriate information is displayed. Displayed trap 
numbers are given in full word format (Axxx). 


Unlike break commands, only one A-Trap command is active at a time. 


AB TRAP] TRAP2 ADDRESS] ADDRESS2 DI D2 (A-Trap Break) 

Causes a break when the condition specified by the parameters is 
satisfied. 

AT TRAP! TRAP2 ADDRESS1 ADDRESS2 DI D2 (A-Trap Trace) 


Traces and displays each A-Trap, but doesn't break, when the condition 
specified by the parameters is satisfied. 


This command continues to display A-Traps until you press the ínterrupt 
button. 


AH TRAP] TRAP2 ADDRESSI ADDRESS? DI D2 (A-Trap Heap zone check) 


TRAP! must be greater than $2E. This command does an HC command just 
before executing each trap in the specified range. It displays the 
first two memory blocks that might contain errors, 


HS TRAP1 TRAP2 (Heap Scramble) 


Scrambles the heap zone, by moving relocatable blocks, when certain 
traps in the specified range are encountered. It always scrambles the 
heap zone as a result of NewPtr, NewHandle, and ReallocHandle calls, 
It scrambles the heap zone as a result of SetHandleSize and SetPtrSize 
if the new length is greater than the current length. 


This command is fastest if you set trapl to $18 and trap2 to $2D. 

The heap zone is not scrambled as a result of traps other than those 
named above. 

AS ADDRESS! ADDRESS2 (A-Trap Spy) 

Calculates a checksum for the specified memory range, and then checks 


it before each trap. Breaks into MacsBug if the checksum doesn't 
match. 
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AX (A-Trap Clear) 


Clears all A-Trap commands. 


Heap Zone Commands 


The heap zone commands act upon the current heap zone. When MacsBug is 
atarted up, the current heap zone is the application heap zone. You 
can toggle the current heap zone between the application heap zone and 
the system heap zone using the HX command. 


Several commands cause MacsBug to scramble the heap zone. When MacsBug 
scrambles the heap zone, it rearranges all the relocatable blocks. 

This is useful for finding illegally used pointers to relocatable data 
structures. 


HX (Heap Exchange) 


Toggles the current heap zone between the system heap zone and the 
application heap zone. 


HC (Heap Check) 


Checks the consistency of the current heap zone. If an inconsistency 
is found, two blocks are displayed. The first appears correct, but 
might have a bad length; the second is definitely garbled. 


HD MASK (Heap Dump) 


MASK is optional. Whether or not MASK is used, it displays each block 
in the current heap zone in the following form: 


BlockAddr Type Size [Flags MP location] [*] [RefNum ID Type] 


The blockAddr points to the start of the memory block. The type is F 
for a free block, P for a pointer, and H for a handle to a relocatable 
block. The size is the physical size of the block, including the 
contents, the header, and any unused bytes at the end of the block. 


For handles (type H), Flags (the high nibble of the master pointer) and 
the master pointer location are given. Flags are: locked (bit 3), 
purgeable (bit 2), resource (bit 1), and unused (bit 9). The asterisk 
marks any immobile object (nonrelocatable blocks and locked relocatable 
blocks). 


For resource file blocks, three additional fields are displayed: the 
resource's reference number, ID number, and type. 


If MASK is omitted, the dump is followed by a summary of the heap 
zone's blocks. It begins with the six characters 'HLP PF’, which 
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represent the six values that follow then. These values are 
H - number of relocatable blocks in the heap zone (handles) 
L - number of relocatable blocks that are Locked 
P - number of Purgeable blocks in the heap zone 

- SPACE, in bytes, occupied by purgeable blocks 
P - number of nonrelocatable blocks in the heap zone (pointers) 
F - total amount of Free space in the heap zone 
Here is a sample summary: 

HLP PF $984 9004 9902 96000792 0917 — 09000354 


Note that block counts are single words, and values representing space 
in bytes are long word quantities. 


1f MASK is used, the summary line displays the block counts of specific 
types of blocks. Possible values for MASK are: 


'H' Relocatable blocks (handles) 

‘pt Nonrelocatable blocks (pointers) 
de iad Free blocks 

'R' Resource blocks 

'xxxx ' Resource blocks of type 'xxxx' 


If MASK is used, the heap summary takes this form: 

CNT ### <# of blocks of MASK type? <Ë bytes in those blocks»? 
You can prematurely terminate an HD command by pressing the Backspace 
key. 
HP MASK (Heap Print) 
If you are using TermBugA or TermBugB, this command can be used to dump 
the heap zone to the other seríal port. Communication is done at 9600 


baud, 8 data bits, 2 stop bits, and mo parity bits, using the XOn/XOf f 
protocol. 


HT MASK (Heap Total) 


Displays just the summary line from a heap zone dump.  MASK works just 
as it does with the HD command. 
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Disassembler Commands 


ID ADDRESS (Instruction Disassemble) 


Disassembles one line at ADDRESS. If ADDRESS is omitted, the next 
logical location is disassembled. This sets the dot symbol to the 
ADDRESS. 


If it is Pascal code that was compiled with the {$D+} option on, and 
symbols have been turned on with the PX command, each address is 
automatically displayed as a routine name plus an offset. 


IL ADDRESS NUMBER (Instruction List) 
Disassembles NUMBER lines starting at ADDRESS. If NUMBER is omitted, a 
screenful of lines is disassembled. If both NUMBER and ADDRESS are 
omitted, a screenful of lines is disassembled starting at the next 
logical location. This command sets the dot symbol to the ADDRESS. 

If it is Pascal code that was compiled with che {$D+} option on, and 
symbols have been turned on with the PX command, each address is 
automatically displayed as a routine name plus an offset. 

You can prematurely terminate an IL command by pressing the Backspace 
key. 

PX (Symbol Toggle) 

Toggles whether or not symbols are displayed. By default, symbols are 


off. This affects the IL, ID, and WH commands. 


Miscellaneous Commands 





F ADDRESS COUNT DATA MASK (Find) 


Searches COUNT bytes from ADDRESS, looking for DATA after masking the 
target with MASK. As soon as a match is found, the ADDRESS and value 
are displayed, and the dot symbol is set to that ADDRESS. To search 
the next COUNT bytes, simply press Return. 


The size of the target (and default MASK) is determined by the width of 
DATA, and can only be l, 2, or 4 bytes. Default MASK has all bits on. 
WH EXPR (Where) 


Displays the number, address, and with MaxBug, the name, of the trap 
specified by EXPR. 
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If EXPR is a name or is less than 512, it displays information for that 
trap. If EXPR is greater than or equal to 512, the trap whose code is 
closest to address EXPR is displayed. This is useful for finding out 
what trap was executing when an error occurred. 


CS ADDRESS] ADDRESS2 (Checksum) 


Checksums the bytes in the range ADDRESS! through ADDRESS2 and saves 
that value. If ADDRESS2 is omitted, it checksums 16 bytes, starting at 
ADDRESSI. If ADDRESS1 and ADDRESS2 are both omitted, it calculates the 
checksum for the last range specified, saves that value, and compares 
it to the previous checksum for that range. If the checksum hasn't 
changed, it prints 'CHKSUM T'; otherwise it prints 'CHKSUM F'. 


CV EXPR (Convert) 
Displays EXPR as unsigned hexadecimal, signed hexadecimal, signed 
decimal, and text. 


RX (Register Exchange) 


Toggles the display mode so that the registers are or are not dumped 
during a trace command. The disassembly of the PC instruction is not 


affected. 


— EEE Ad 


Handy Hints 


Stopping the Disk Drive 


When you are using the debugger, the disk drives don't stop spinning as 
they usually do. You can get a disk drive to stop by doing the 
following: 


l. Enter DM PC and remember the first word that is displayed. 


2. Enter SM PC 6ØFE, the instruction BRA *-2, which is an infinite 
loop. 


3, Enter G and wait for the drive to stop spinning. 
4. When the drive stops spinning, press the interrupt button. 


5. Put the old word back into memory. 
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Using No-ops 


If you want to no-op out an instruction, replace the instruction with 
the number $4E71, the no-op opcode. 


Using Macs Bug with the Lisa Workshop 


If you are using the Lisa Workshop development system, you can invoke 
MacsBug by declaring and calling the following procedure: 


PROCEDURE MacsBug; INLINE SA9FF; 


This procedure drops into MacsBug and dísplays the message 'USERBRK'. 
It then does a normal exception entry into MacsBug. 


If you want to display debugging information, declare and call this 
procedure: 


PROCEDURE MacsBugPrint (str: str255); INLINE $ABFF; 


When the SABFF trap is encountered, MacsBug assumes that the top of the 
user's stack has a pointer to a Pascal string. It prints out the 
string, displays the message 'USERBRK', and does a normal exception 
entry into MacsBug. 


The Lisa Workshop Pascal compiler has an option that lets you 
symbolically display the names of routines and functions in MacsBug. 

If you compile your program using the {$D+} option, procedure names are 
automatically placed in the code at the end of each procedure or 
function. If you want to use the symbols, you should use PX to turn on 
symbolic display. 


rw” ru. 


"+ 


ru 


>: 


Chapter 8 


The Resource Compiler 


About This Chapter 93 


About This Chapter 


This chapter describes RMaker, an application that is used to produce 
resource files and to integrate resources into applications. 


The first part of this chapter describes RMaker. The next part of the 
chapter describes how to create an RMaker input file using predefined 
resource types and user-defined resource types. The final part of the 
chapter tells how to use RMaker to create a new resource file from the 
input file. 


About RMaker 


RMaker is the Macintosh 68990 Development System's Resource Compiler. 
It is very similar to the RMaker program in the Lisa Workshop, but some 
changes have been made to the syntax. Be careful if you are converting 
resource files from one system to the other. 


RMaker takes a text file as input and produces a resource file. The 
text file contains an entry for each resource, as described below. 
These entries can specify all information necessary to define the 
resources, or they can cause existing resources to be read from other 
files. 


For example, during program development, you'll typically use separate 
application and resource files. Once the application is finished, you 
should combine these files. Simply use the INCLUDE statement to read 
in the application created by the Linker. It is already stored as 
resources of type ‘CODE’. 


RMaker Input Files 


An RMaker input file is a text file that may be created using the 
Editor. By convention, RMaker input files have the extension «R. 


RMaker ignores all comment lines and blank lines (except in some cases 
a blank line may be required). It also ignores leading and embedded 
spaces (except in lines defined to be strings). Comment lines begin 
with an asterisk. To put comments at the end of other RMaker lines, 
precede the comment with two consecutive semicolons (;;). 


Naming the Resource File 


The first nonblank and noncomment line of the input file specifies the 
name of the resource file to be created. If the filename has the 
extension .Rel, a file is generated that can be linked using the Linker 
(see the section on resources in Chapter 4). If the file is to be an 
application, it should have no extension. If not, the file will be a 
resource file and should have the extension .Rsrc. The line following 
the resource's filename should either specify the File type and creator 
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bytes for the Finder or be blank. For example, the two lines 


NewResFile.Rsrc 
PNTGMPNT 


specify the file named NewResFile.Rsrc as the output file, and the 
bytes 'PNTGMPNT' as the type and creator bytes. These bytes tell the 
Finder that the file is a painting file, created by MacPaint. (The 
Finder will try to launch MacPaint if you select and open this file!) 
More typically, these two lines will look like this: 


MyApplication 
APPLMY AP 


This designates the file MyApplication as the output file. The file is 
an application (type 'APPL') of type 'MYAP'. 


If you do not specify a value for these bytes, they are set to Ø. 


Appending to an Existing Resource File 


If you wish to add the resources defined in your input file to those in 
an existing resource file, simply precede the filename with an 
exclamation poínt. For example 

'OldResFile.Rsrc 


tells RMaker to add the new resources to the file OldResFile.Rsrc. 


Adding Resources 


The rest of the resource file consists of INCLUDE statements and "Type 
statements". 


INCLUDE statements are used to read in entire resource files. An 
INCLUDE statement looks like this: 


INCLUDE filename 
Type statements consist of the word "Type" followed by the resource 
type and, below that, one or more resource definitions. The resource 


type must be capitalized to match a predefined resource type. 


The following statement creates three resources of type 'STR '. 
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TYPE STR 
| 

This is a string 
2 

Gnirts a si siht 
13 

Hits is a grints 


It is not necessary for all resources of a given type to be declared 
together; however, all resources of a type must have unique resource 
IDs. If you specify a resource ID that is already in use, the new 
resource replaces the old one. 


A resource looks like this: 


[resource name] ‚resource ID [(resource attribute byte)] 
type-specific data 


The square brackets indicate that the resource name and resource 
attribute byte are optional. Don't place these brackets in your input 
file. The comma before the resource ID is mandatory. The default 
attribute byte is Ø. Here are some sample resource definitions: 


TYPE STR 

NewStr ‚4 (32) 

This resource has a name and an attribute byte!! 
ES 

This one has only a resource ID. 

MyNewStr,6 

This has a name and a resource ID. 


The type-specific data is different for each resource type. As you 
have probably guessed, the type-specific data for a ‘STR ' resource is 
simply a string. The next section describes the type-specific data for 
the resource types defined by RMaker. 


Defined Resource Types 


RMaker has 12 defined resource types:  'ALRT', 'BNDL', 'CNTL', 'DITL', 
'DLOG', 'FREF', 'GNRL', 'MENU', 'PROC', "STR ', 'STRÉ', and "WIND". 

The format of the type-specific data for each type is shown by example, 
below. The type 'GNRL' is used to define your own resource types. It 
is explained later. 


Syntax of RMaker Lines 


There are just a few general rules that apply to lines read by RMaker. 


- Leading and embedded blanks are ígnored, except when necessary to 
separate multiple numbers on a line, or when they are part of a 
string. 
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- Numbers are decimal, unless specified otherwise. 


- RMaker is sensitive to line breaks. Thus if a type description, 
below, shows four values on a single line, you must put four 
values on a single line. 


Two special symbols can be used in resource definitions: the 
continuation symbol (++) and the enter ASCII symbol (1). 


++ goes at the end of a line that is continued on the next line. 


\ precedes two hexadecimal digits. That ASCII character is 
entered into the resource definition. 


Look at the description of the 'STR ' type for examples of these 
special symbols. As previously mentioned, blank lines are ignored. To 
enter a blank line that isn't ignored, use V2Ø. 


You will notíce that some of the resources are listed as templates, 
while others are not. A template is a list of parameters used to build 
a Toolbox object; it is not the object itself. 


ALRT Alert Template 
TYPE ALRT 
,128 ;; resource ID 
50 59 259 259 ;; top left bottom right 
l :; resource ID of item list 
7FFF :; stages word in hexadecimal 
BNDL Application Bundle 
TYPE BNDL 
,128 ;; resource ID 
MPNT 9 ;; bundle owner 
ICN# ;; resource type 
4 128 1 129 -; local ID Ø maps to resource ID 128; 1 to 129 
FREF ;; resource type 
Ø 128 1 129 ;; local ID Y maps to resource ID 128; 1 to 129 


Note: the number of mappings from local ID to resource ID is variable» 
Simply include multiple mappings on å single line. 


CNTL Control Template 
TYPE CNTL 
‚138 s; resource ID 
Stop ;; title 
244 40 260 80 ;; top left bottom right 
Invisible '5 see note 


Y -; ProcID (control definition ID) 
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Ø :: RefCon (reference value) 
319 ;; minimum maximum value 


Note: Controls can be defined to be Visible or Invisible. Only the 
first character (V or I) is significant. 


DITL Dialog or Alert Item List 
TYPE DITL 
,129 ;; resource ID 
5 3; 5 items in list 
staticText :; static text dialog item (see note) 
20 29 32 109 ;; top left bottom right 
Whoopie ;; message 
editText ;; editable text dialog item (see note) 
20 129 32 200 ;; top left bottom right 
Default message ;; message 
radioButton ;; radio button dialog item (see note) 
4d 49 60 159 ;; top left bottom right 
Hello ;; message 
checkBox Disabled ;; disabled dialog item (see note) 
75 48 95 159 >; top left bottom right 
GoodBye ;; message 
button ss button dialog item (see note) 
75 169 95 299 ;; top left bottom right 
Hi! ;; message 


Note: Five types of dialog items are defined: Static text, Editable 
text, Radio Buttons, Check Boxes, and Buttons. These items are assumed 
to be enabled. Otherwise you may specify Disabled. Only the first 
character of an item definition word is significant (S,E,R,C,B,D). 


DLOG Dialog Template 
TYPE DLOG 
3 ;; resource ID 
This is a díalog box. ;; message 
109 199 199 250 ;; top left bottom right 
Visible GoAway ;; box status (see note) 
$ ;; procID (dialog definition ID) 
4 s; refCon (reference value) 
129 ;; ID of item list ('DITL', above) 


Note: A dialog box can be Visible or Invisible. GoAway and NoGoAway 
determine whether or not the dialog box has a close box. Only the 
fírst characters (V,I,G,N) are signíficant. 
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FREF File Reference 
TYPE FREF 
,128 ;; resource ID 
APPL Ø s; file type, local ID of icon 
,129 ;; resource ID 
TEST 127 myFile 35 file type, local ID of icon, filename 


Note: If there is no fílename, it can be omitted. 


MENU Menu 
TYPE MENU 

så ;; resource ID 
Transfer s; menu title 
Edit :3 item I 
Asm ;; item 2 
Link ;; item 3 
(- ;; item 4 (draw a line) 
Exec ;; item 5 

53 MUST be followed by a blank line!! 

PROC Procedure 
TYPE PROC 

‚128 ;; resource ID 
MyProcedure 3; filename 


This type is used to create resources that contain code. It reads the 
first code segment from an application file (the ‘CODE’ resource with 
ID = 1), strips the first four bytes off of it (used by the Segment 
Loader), and saves it as a resource of type 'PROC'. It is useful for 
defining code types such as 'DRVR', 'WDEF', and 'PACK'. An example is 
given below in the section on creating your own resource types. 


STR String 
TYPE STR 'STR ' (space required) 


$3 
så ;; resource ID 
This is a string ;; and a string 


23 ;; resource ID 
This is a string + ;; and a long string 
that shows the line ++ 
continuation characters. 


,25 (32) ;; resource ID, optíonal attríbute byte 
I've got attributes! ;; and a stríng 
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AT ;; resource ID 
Testing, 131, 132, 133 ;; "Testing, 1, 2, 3' the hard way 


STR# A Number of Strings 


TYPE STR# 

me | s; resource ID 
4 ;; number of strings 
This is string one ;; and the strings... 


And string two 
Third string 
Bench warmer 


WIND Window Template 
TYPE WIND 
,128 
Wonder Window s; title 
49 89 1206 399 ;; top left bottom right 
Invisible GoAway :; window status (see note) 
4 ;; ProcID (window definition ID) 
9 :; RefCon (reference value) 


Note: A Window can be Visible or Invisible; GoAway and NoGoAway 
determine whether or not the window has a close box. Only the first 
character of each option (V,I,G,N) is significant. 


Creating Your Own es 
There are two ways to create your own resource types. The first is to 


equate a new type to an existing type. For example, you can create a 
resource of type 'DRVR' like this: 


TYPE DRVR = PROC ;; type 'DRVR' is just like 'PROC' 
,17 (32) ;; resource ID, attribute byte 
MyDriver 5 Filename 


The file MyDriver should be a single-segment application, as created by 
the Linker. Recall that the 'PROC' type reads in the resource of type 
‘CODE’ with ID = 1; then it strips off the header bytes. 


The other way to create your own type is to equate the new type to 
'GNRL' and then to specify the precise format of the resource. A set 
of element type designators lets you define the type of each element 
that is to be placed in the resource. 


Here are the element type designators: 


P Pascal string 
. Š String without length byte 
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«I Decimal integer 

L Decimal long integer 

oH Hexadecimal 

oR Read resource from file. .R is followed by: 


filename type ID 


For example, to define a resource of type 'CHRG' consisting of the 
integer 57 followed by the Pascal string ‘Finance charges’, you could 
use the following type assignment: 


TYPE CHRG = GNRL ;; define type 'CHRG' 
‚289 ;; resource ID 

«I ;; a decimal integer 

57 

P «3 a Pascal string 


Finance charges 


A more practical example: An application that has its own icon must 
define an icon list and reference ít using 'FREF' (described above). 
Such an icon list can be defined as follows: 


TYPE ICN# = GNRL :; icon list for an application 
,128 ;; resource ID 

eH ;; enter 2 icons in hexadecimal 

$091 9902 3903 PIPA :; each is 32 bits by 32 bits 

OO7D Q97E Q0@7F 0080 "+ for 128 words total 


The .R type designator is used to include an existing resource as part 
of a new resource type. For example, to read an existing 'FONT' 
resource into a new resource of type 'FONT', use the following resource 


definition: 


TYPE FONT = GNRL >; define a new type 

‚268 ;; resource ID 
«R s; read from the System file 
System FONT 268 >; the 'FONT' resource with ID=268 


— a n Cm A. — sr 


Using RMaker 


Once you have created the input file to RMaker, the hard work is done. 
Simply select and open the application RMaker. The standard file 
selection window is automatically opened. Select the file you want to 
compile, and off it goes. 


By default, the standard file selection window displays all the text 
files on the disk. If you want to display only the .R files, Cancel 
the selection window, choose .R Filter from the File menu, then choose 
Compile from the File menu to redisplay the file selection window. 
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¿AAA Resource Compiler SEE 
Source File Window R | Output File MDS2:Window Rsrc ME 


StaticText I I 
15 20 36 300 Data Size: 334 


This sample program was written Map Size: 134 
StaticText Total Size: 468 


35 20 56 300 
just to prove it could be done! 


é File Transfer 


+ WIND Resource #1 specifies th 
E * for the window in which editir 
* call to GetNewWindow. 


Type WIND 
1 


A Sanpie 
S0 40 300 459 


Visible NoGoRway 
0 





When RMaker is compiling a file, the name of the source file is 
displayed in the upper left of the window, and the name of the output 
file is displayed in the upper right. As the file is compiled, the 
current size of the resource data, the size of the resource map, and 
the total size are tracked on the right half of the screen. In 
addition, as each line is compiled, it is displayed on the screen. 


If there are no errors in the RMaker input file, a resource file with 
the specified name is created. 


Errors in the Input File 


If an error occurs, the line containing the error is the last line on 
the screen. RMaker then displays a box with an error message in it. 


RMaker errors are listed in an appendix. 


Appendix A 


Sample Program Listing 
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Ce 
The Window Sample Program 


; File Window.Asm 


a a €um uam FE uum uuo D m GMP uar á... à ED OD ED Ñ. GP ee s... m cnc mcm m "K 
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This application aestu a a window within which you can enter and edit 
text. Program control is through three menus: the Apple menu, the File 
; menu, and the Edit menu. 


The Apple menu has the standard desk accessories and an About feature. 
The File menu lets you quit the application. 


The Edit menu lets you cut, copy, paste, and clear the text in the window 
or in the desk accessories. Undo is provided for desk accesories only. 
Command key equivalents for undo, cut, copy, and paste are provided. 
Cutting and pasting between the application and the desk accessories is 
not supported. This requires use of the Scrap Manager. 


; This program requires the use of a resource file called "Window.Rsrc" 
: Window.Rsrc is created from "Window.R" using RMaker 


— A MMMM INCLUDES ----—-—---------—-------9——--2----- 
Include MacTraps.D ; Use System and ToclBox traps 
Include ToolEqu.D ; Use ToolBox equates 


44-2 A Use Gf Registers: Ss u AAA 
; Operating System and Toolbox calls always preserve D3-D7, and A2-A4. 
Register use: A5-A7 are reserved by the system 


D1-D3, AO-Al are unused 
DO is used as a temp 


we w `. 


ModifyReg EQU D4 > D4 holds modifier bits from GetNextEvent 
MenuReg EQU DS : D5 holds menu ID from MenuSelect, MenuKey 
MenultemReg EQU Dé : D6 holds item ID from MenuSelect, Menukey 
AppleHReg EQU D? + D? holds the handle to the Apple Menu 
TextHReg EQU A2 ; A2 is a handle to the TextEdit record 
WindowPReg EQU A3 ; A3 is a pointer to the editing window 
EditHReg EQU Ad ; A4 is a handle to the Edit menu 


pone = am mm enn EQUATES -------------------------------- 


; These are equates associated with the resources 
; for the Window example. 


AppleMenu EQU ; First item in MENU resource 
AboutItem EQU ; First item in Apple menu 

FileMenu EQU : Second item in MENU resource 
QuitItem EQU : First item in File menu 

EditMenu EQU ; Third item in MENU rescurce 


; Items in Edit menu 
(Item 2 is a line) 


UndoItem EQU 
CutItem EQU 
CopyItem EQU 
Pasteltem EQU 
Clearltem EQU 


AboutDialog  EQU 
ButtonItem EQU 
ASample EQU 


About dialog is DLOG resource #1 
First item in DITL used by DLOG #1 
Sample Window is WIND resource #1 


PRR HU PWR rH Pr 
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: These are modifier bits returned by the GetNextEvent call. 


activeBit EQU Q : Bit position of de/activate in Modify 
emdKey EQU 8 ; Bit position of command key in Modify 
shiftKey EQU 9 ; Bit position of shift key in Modify 
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: XDEF all labels that are to be symbolically displayed by debugger. 


XDEF Start 

XDEF InitManagers 

XDEF OpenResFile 

XDEF SetupMenu 

XDEF SetupWindow 

XDEF SetupTextEdit 

XDEF Activate 

XDEF Deactivate 

XDEF Update 

XDEF KeyDown 

XDEF MouseDown 

XDEF SystemEvent 

XDEF Content 

XDEF Drag 

XDEF InMenu 

XDEF About 
, Maaa aaea mee Main Program Fass ERW DE 
Start 

BSR InitManagers ; Initialize managers 

BSR OpenResFile ; Open the resource file 

BSR SetupMenu ; Build menus, draw menu bar 

BSR SetupWindow : Draw Editing Window 

BSR SetupTextEdit ; Initialize TextEdit 
Event Loop ; MAIN PROGRAM LOOP 

SystemTask : Update Desk Accessories 

7 PROCEDURE TEIdle (hTE:TEHandle); 

MOVE.L TextHReg, - (SP) : Get handle to text record 

 TEIdle ; blink cursor etc. 

; FUNCTION GetNextEvent (eventMask: INTEGER; 

: VAR theEvent: EventRecord) : BOOLEAN 

CLR - (SP) ; Clear space for result 

MOVE KSOFFF, - (SP) ; Allow 12 low events 

PEA EventRecord : Place to return results 

GetNextEvent : Look for an event 

MOVE (SP}+, D0 ; Get result code 

BEQ EventLoop ; No event... Keep waiting 

BSR HandleEvent ; Go handle event 

BEQ EventLoop : Not Quit, keep going 

RTS ; Quit, exit to Finder 


Note: When an event handler finishes, it returns the 2 flag set. If 


; Quit was selected, it returns with the Z flag clear. An RTS is 


; guaranteed to close all files and launch the Finder. 
Bm te -- Tom InitManagers TE ee 
InitManagers 
PEA -4 (AS) ; Quickdraw's global area 
_InitGraf ; Init Quickdraw 
InitFonts ; Init Font Manager 
MOVE.L #SOQOOFFFF, DO : Flush all events 
_FlushEvents 
InitWindows ; Init Window Manager 
"InitMenus ; Init Menu Manager 
CLR.L - (SP) ; No restart procedure 
_InitDialogs ; Init Dialog Manager 
TEInit ; Init Text Edit 
eres ; Turn on arrow cursor 
TS 


m iw wo Ww (çv 


| 
m 


wm om m 


"m nm onm m om m m m m om om m om m m m m 


The Window Sample Program 107 


OpenResFile 


Na Se Se Ma You `. 


For development, we are keeping the resources ina separate file. The 
application can be sped up by adding the resources to the application’s 
file, which makes the enResFile call unneccessary. Note: normally the 
explicit mention of MDS2 is considered bad style; the resource file 
should be on the same volume as the program. However, it must be done 
like this or Transfer looks on the wrong volume. 


; FUNCTION OpenResFile (fileName: str255) : INTEGER; 


CLR ~ (SP) ; Space for refNum 
PEA 'MDS2:Window.Rsrc' ; Name of resource file 
OpenResFile ; Open it 
MOVE (SP)+,DO ; Discard refNum 
RTS 
A AAA SetupMenu == === SA 
SetupMenu 


Ne Yp a Mo Sr 


. 
, 


. 
+ 


På 
, 


The names of all the menus and the commands in the menus are stored in the 
resource file. The way you build a menu for an application is by reading 
each menu in from the resource file and then inserting it into the current 
menu bar. Desk accessories are read from the system resource file and 
added to the Apple menu. 


Apple Menu Set Up. 
; FUNCTION GetMenu (menu ID:INTEGER): MenuHandle; 


CLR.L -(SP) ; Space for menu handle 

MOVE #AppleMenu, - (SP) ; Apple menu resource ID 
GetRMenu ; Get menu handle 

MOVE.L (SP) , AppleHReg ; Save for later comparison 

MOVE.L (SP), - (SP) : Copy handle for AddResMenu 


; PROCEDURE InsertMenu (menu:MenuHandle; beforeID: INTEGER); 
CLR - (SP) ; Append to menu 
_InsertMenu ; Which is currently empty 
Add Desk Accessories Into Apple menu (Apple menu handle already on stack) 
; PROCEDURE AddResMenu (menu: MenuHandle; theType: ResType); 
MOV 


E.L &'DRVR',- (SP) ; Load all drivers 
_AddResMenu ; And add to Apple menu 


File Menu Set Up 
; FUNCTION GetMenu (menu ID:INTEGER): MenuHandle; 


CLR.L - (SP) ; Space for menu handle 
MOVE #FileMenu, - (SP) ; File Menu Resource ID 
_GetRMenu ; Get File menu handle 


; PROCEDURE InsertMenu (menu:MenuHandle; beforeID: INTEGER); 
- (SP) ; Append to list 
_InsertMenu ; After Apple menu 


Edit Menu Set Up 
; FUNCTION GetMenu (menu ID: INTEGER}: MenuHandle; 


CLR.L - (SP) ; Space for menu handle 
MOVE #EditMenu, - (SP) ; Edit menu resource ID 
Get RMenu ; Get handle to menu 

MOVE.L (SP) ,EditHReg ; Save for later 


; Leave on stack for Insert 
: PROCEDURE InsertMenu (menu:MenuHandle; beforeID: INTEGER); 


- (SP) ; Append to list 
_InsertMenu ; After File menu 
DrawMenuBar ; Display the menu bar 


RTS 
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SetupWindow 
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; FONCTION GetNewWindow (windowID: 
CLR.L - (SP) 
MOVE #ASample, - (SP) 
PEA . WindowStorage (A5) 
MOVE.L &-1,- (SP) 
GetNewWindow 
MOVE.L (SP),WindowPReg 
; PROCEDURE SetPort (gp: GrafPort) 
SetPort 
RTS 
Pp A A A SetupTextEdit 
SetupTextEdit 


* 
; 
, 
, 


the resource file, 


it will be displayed. 


—— — — — — — — — — ^ — SE — — — — — — — — — — — — — — — — — 


The window parameters are stored in our resource file. Read them from 
the file and draw the window, then set the port to that window. Note that 
the window parameters could just as easily have been set using the call 
NewWindow, which doesn’t use the resource file. 


INTEGER; wStorage: Ptr; 
behind: WindowPtr) : WindowPtr; 


Space for window pointer 
Resource ID for window 
Storage for window 

Make it the top window 
Draw the window 

Save for later 


Pointer still on stack 
Make it the current port 
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Create a new text record for TextEdit, and define the window within which 
Note that if the window boundaries are changed in 


DestRect and ViewRect will have to be changed too. 


: PROCEDURE TENew (destRect,viewRect: Rect): TEHandle; 


CLR.L - (SP) ; Space for text handle 

PEA DestRect ; DestRect Rectangle 

PEA ViewRect ; ViewRect Rectangle 

TENew ; New Text Record 

MOVE.L (SP) +, Text HReg ; Save text handle 

RTS 
A ÀÀÀ—À— o — Event Handling Routines —----------------------- 
HandleEvent 


: Use the event number as an index into the Event table. These 12 events 
; are all the things that could spontaneously happen while the program is 


in the main loop. 


MOVE 
MOVE 
ADD 
MOVE 
JMP 


EventTable 


DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 


Modify,ModifyReg 
What, DO 

DO,DO 
EventTable(DO),DO 
Event Table (DO) 


NextEvent-EventTable 
MouseDown-EventTable 
NextEvent-EventTable 
KeyDown-EventTable 
NextEvent-EventTable 
KeyDown-EventTable 
Update-EventTable 
NextEvent-EventTable 
Activate-EventTable 
NextEvent-EventTable 
NextEvent-EventTable 
NextEvent-EventTable 


wç ug `. Vs å 
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More useful in a reg 
Get event number 

*2 for table index 
Point to routine offset 
and jump to it 


Null Event (Not used) 
Mouse Down 

Mouse Up (Not used) 
Key Down 

Key Up (Not used) 
Auto Key 

Update 

Disk (Not used) 
Activate 

Abort (Not used) 
Network (Not used) 
I/O Driver (Not used) 


| | | | | | | | | | 
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Activate 


= ; An activate event is posted by the system when a window needs to be 
activatıd or deactivated. The information that indicates which window 
needs to be updated was returned by the NextEvent call. 


. 
r 


“ 
, 


CMP.L Message, WindowPReg ; Was it our window? 
BNE NextEvent ; No, get next event 

- BTST #ActiveBit,ModifyReg ; Activate? 
BEO Deactivate ; No, go do Deactivate 


To activate our window, activate TextEdit, and disable Undo since we don’t 
support it. Then set our window as the port since an accessory may have 
changed it. This activate event was generated by SelectWindow as a result 
of a click in the content region of our window. If the window had scroll 
bars, we would do ShowControl and HideControl here too. 


“ep “1 ‘a “a de 


; PROCEDURE TEActivate (hTE: TEHandle); 


MOVE.L TextHReg, - (SP) ; Move Text Handle To Stack 
_TEActivate ; Activate Text 
E : PROCEDURE Disableltem (menu:MenuHandle; item: INTEGER); 

MOVE.L EditHReg, - (SP) : Get handle to the menu 
MOVE *Undoltem, - (SP) ; Enable lst item (undo) 
_Disableltem 

SetOurPort ; used by InAppleMenu 
> PROCEDURE SetPort (gp: GraphPort) ; Set the port to us, since 
MOVE.L WindowPReg, - (SP) ; an accessory might have 
_SetPort ; changed it. 

NextEvent 
MOVEO #0,D0 ; Say that it’s not Quit 
RTS ; return to EventLoop 


Deactivate 


; To deactivate our window, turn off TextEdit, and Enable undo for the desk 
: accessories (which must be active instead of us). 


: PROCEDURE  TEDeActivate (hTE: TEHandle) 


MOVE.L TextHReg,- (SP) ; Get Text Handle 

_TeDeActivate ; Un Activate Text 

: PROCEDURE EnableItem (menu:MenuHandle; item: INTEGER); 
MOVE.L EditHReg,-(SP) ; Get handle to the menu 

MOVE #Undoltem, - (SP) ; Enable ist item (undo) 
EnableItem 

BRA NextEvent : Go get next event 


Update 


: The window needs to be redrawn. Erase the window and then call TextEdit 
; to redraw it. 


: PROCEDURE BeginUpdate (theWindow: WindowPtr); 
MOVE.L WindowPReg, - (SP) ; Get pointer to window 
_BeginUpDate ; Begin the update 


: EraseRect (rUpdate: Rect); 
BA ViewRect > Erase visible area 
_EraseRect 
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; TEUpdate (rUpdate: Rect; hTE: TEHandle); 
PEA 


ViewRect ; Get visible area 

MOVE.L TextHReg, - (SP) ; and handie to text 
_TEUpdate ; then update the window 
; PROCEDURE EndUpdate (theWindow: WindowPtr); 
MOVE.L WindowPReg, - (SP) ; Get pointer to window 

EndUpdate ; and end the update 
BRA NextEvent ; Go get next event 

KeyDown 


; Å key was pressed. First check to see if it was a command key. If so, 
; go do it. Otherwise pass the key to TextEdit. 


> 
BTST #CmdKey, Modi fyReg ; Is command key down? 
BNE CommandDown ; If so, handle command key 


; PROCEDURE TEKey (key: CHAR; hTE: TEHandle); 
MOVE Message+2, - (SP) Get character 


MOVE.L TextHReg, - (SP) ; and text record 
TEKey ; Give char to TextEdit 
BRA NextEvent ; Go get next event 
CommandDown 


The command key was down. Call MenuKey to find out if it was the command 
key equivalent for a menu command, pass the menu and item numbers to Choices. 


we we 


; FUNCTION MenuKey (ch:CHAR): LongInt; 
CLR.L ~ (SP) ; Space for Menu and Item 


MOVE Message+2,- (SP) ; Get character 
MenuKey ; See if it's a command 
MOVE (SP) +, MenuReg ; Save Menu 
MOVE (SP) *, MenuItemReg ; and Menu Item 
BRA Choices ; Go dispatch command 
Re me === == Mouse Down Events And Their Actions---------------------- 
MouseDown 


; If the mouse button was pressed, we must determine where the click 
; occurred before we can do rep ar Dd. Call FindWindow to determine 
: where the click was; dispatch the event according to the result. 


; FUNCTION FindWindow {thePt: Point; 
, VAR whichWindow: WindowPtr): INTEGER; 


CLR - (SP) ; Space for result 
MOVE.L Point,-(SP) ; Get mouse coordinates 
PEA WWindow ; Event Window 
FindWindow ; Who's got the click? 
MOVE (SP) +,DO ; Get region number 
ADD DO,DO : *2 for index into table 
MOVE WindowTabie(DO),DO ; Point to routine offset 
JMP WindowTable (D0} ; Jump to routine 
WindowTable 
DC.W NextEvent-WindowTable ; In Desk (Not used) 
DC.W InMenu-WindowTable ; In Menu Bar 
DC.W SystemEvent-WindowTable ; System Window 
DC.W Content-WindowTable ; In Content 
DC.W Drag-WindowTable ; In Drag 
DC.W NextEvent-WindowTable ; In Grow (Not used) 
DC.W NextEvent-WindowTable ; In Go Away (Not used) 
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SystemEvent 


; The mouse button was pressed in a system window. SystemClick calls the 
; appropriate desk accessory to handle the event. 


; PROCEDURE SystemClick {theEvent: EventRecord; 
: theWindow: WindowPtr} ; 


PEA EventRecord ; Get event record 

MOVE.L WWindow,- (SP) ; and window pointer 
SystemClick ; Let the system do it 

BRA NextEvent ; Go get next event 


Content 


The click was in the content area of a window. If our window was in 
front, then call Quickdraw to get local coordinates, then pass the 
coordinates to TextEdit. We also determine whether the shift key was 
pressed so TextEdit can do shift-clicking. If our window wasn't in 
front, move it to the front, but don't process click. 


"e Se “a Sa “a 


CLR.L - (SP) ; clear room for result 
FrontWindow ; get FrontWindow 

MOVE.L (SP) *,DO ; 1s front window pointer 

CMP.L WindowPReg,DO ; same as our pointer? 

BEQ.S 41 ; Yes, cali TextEdit 


; We weren't active, select our window. This causes an activate event. 


; PROCEDURE SelectWindow (theWindow: WindowPtr); 


MOVE.L WWindow,- (SP) ; Window Pointer To Stack 
SelectWindow ; Select Window 
BRA NextEvent ; and get next event 


41 

; We were active, pass the click (with shift) to TextEdit. 
; PROCEDURE GlobalToLocal (VAR pt:Point); 
EA 


P Point ; Mouse Point 

 GlobalToLocal : Global To Local 

; PROCEDURE TEClick (pt: Point; extend: BOOLEAN; hTE: TEHandle); 
MOVE. L Point,-(SP) ; Mouse Point (GTL) 

BTST #shiftKey, Modi fyReg 


; Is shift key down? 
SNE DO ; True if shift down 


; Note: We want the boolean in the high byte, so use MOVE.B. The 68000 
? pushes an extra, unused byte on the stack for us. 


MOVE.B DO, - (SP) 

MOVE.L TextHReg, - (SP) ; Identify Text 
TEClick ; TEClick 

HRA NextEvent ; Go get next event 


Drag 
; The click was in the drag bar of the window.  Draggit. 
; DragWindow (theWindow:WindowPtr; startPt: Point; boundsRect: Rect); 


MOVE.L WWindow, ~ (SP) ; Pass window pointer 
MOVE.L Point, - (SP) ; mouse coordinates 
PEA Bounds ; and boundaries 
DragWindow ; Drag Window 

RA NextEvent : Go get next event 
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InMenu 


` 
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The click was in the menu bar. Determine which menu was selected, then 
call the appropriate routine. 


; FUNCTION MenuSelect (startPt:Point) : LongInt; 


CLR.L - (SP) : Get Space For Menu Choice 
MOVE.L Point, (SP) : Mouse At Time Of Event 
MenuSelect ; Menu Select 

MOVE (SP) *, MenuReg ; Save Menu 

MOVE (SP) +, MenultemReg ; and Menu Item 


On entry to Choices, the resource ID of the Menu is saved in the low 
word of a register, and the resource ID of the Menultem in another. 
The routine MenuKey, used when a command key is pressed, returns the same 


info. 


Choices ; Called by command key too 

CMP #AppleMenu, MenuReg ; Is It In Apple Menu? 

BEQ InAppleMenu ; Go do Apple Menu 

CMP #FileMenu, MenuReg ; Is It In File Menu? 

BEQ InFileMenu ; Go do File Menu 

CMP #EditMenu, MenuReg ; Is It In Edit Menu? 

BEQ InEditMenu ; Go do Edit Menu 
ChoiceReturn 

BSR UnHiliteMenu ; Unhighlight the menu bar 

BRA NextEvent ; Go get next event 
InFileMenu 


Fj 


If it was in the File menu, just check for Quit since that's all there is. 


CMP +QuitItem, MenultemReg ; Is It Quit? 
BNE.S ChoiceReturn ; No, Go get next event 
BSR UnHiliteMenu ; Unhighlight the menu bar 
MOVE #-1, DQ ; say it was Quit 
RTS 

InEditMenu 
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First, call SystemEdit. If a desk accessory is active that uses the Edit 
menu (such as the Notepad) this lets it use our menu. 

Decide whether it was cut, copy, paste, or clear. Ignore Undo since we 
didn‘t implement it. 


BSR SystemEdit ; Desk accessory active? 
BNE.S ChoiceReturn ; Yes, SystemEdit handled it 
CMP #CutItem,MenultemReg ; Is It Cut? 

BEQ Cut ; Yes, go handle it 

CMP #CopyItem, MenultemReg ; Is it gap: 

BEQ Copy : Yes, go handle it 

CMP iPasteltem, MenultemReg; Is it Paste? 

BEQ Paste ; Yes, go handle it 

CMP #ClearItem,MenultemReg; Is it Clear? 

BEQ Clear ; Yes, go handle it 
BRA.S ChoiceReturn ; Go get next event 


mt TAN 
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put 
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InAppleMenu 


; It was in the Apple menu. 


desk accessory. 


CMP 
BEO 


; PROCEDURE 


_GetItem 

; FUNCTION 
CLR 

PEA 


OpenDeskAcc 
MOVE 


GoSetOurPort 


E — —— — >" ee ee vn a c — — — c ee eee 


Copy 


Paste 


Clear 


; SystemEdit does undo, cut, 


BSR 
BRA.S 


; PROCEDURE 
MOVE.L 
TECut 
BRA.S 


; PROCEDURE 
MOVE.L 
TECopy 
BRA.S 


; PROCEDURE 
MOVE.L 
TEPaste 
BRA.S 


; PROCEDURE 
MOVE.L 
TEDelete 
BRA.S 
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If it wasn't About, then it must have been a 


If so, open the desk accessory. 


Is It About? 
If So Goto About... 


#About Item, MenultemReg; 
About : 


GetItem (menu: MenuHandle; item: INTEGER; 
VAR itemString: Str255); 


AppleHReg, - (SP) ¿ Look in Apple Menu 
MenuItemkeg, - (SP) ; What Item Number? 
DeskName ; Get Item Name 


Get Item 


OpenDeskAcc (theAcc: Str255) : INTEGER; 


-(SP) ; Space For Opening Result 

DeskName ; Open Desk Acc 
; Open It 

(SP) *,DO ; Pop result 

SetOurPort ; Set port to us 

ChoiceReturn ; Unhilite menu and return 

Text Editing Routines He nn 

¿ CUT 


TECut (hTE: TEHandle); 
TextHReg, - (SP) ; Identify Text 
; Cut it and copy it 


ChoiceReturn Go get next event 
; COPY 
TECopy (hTE: TEHandle); 
TextHReg, - (SP) ; Identify Text 
; Copy text to clipboard 
ChoiceReturn ; Go get next event 


; PASTE 


TEHandle}; 
; Identify Text 
; Paste 
; Go get next event 


TEPaste (hTE: 
TextHReg, - (SP) 


ChoiceReturn 


TEDelete (hTE: TEHandle); 
TextHReg, - (SP) : Point to text 
; Clear without copying 
ChoiceReturn ; Go get next event 
and ciear for desk accessories. 


copy, paste, 


: It returns False (BEQ) if the active window doesn't belong to a 
desk accessory. 


SystemEdit 


; FUNCTION 
CLR 


MOVE 
SUBQ 

SysEdit 
MOVE.B 
RTS 


SystemEdit (editCmd: INTEGER): BOOLEAN; 


~ (SP) ; Space for result 

MenultemReg, - (SP) : Get item in Edit menu 

#1, (SP) ; SystemEdit is off by 1 
# Do It 

(SP) *,DO ; Pop result 


BEQ if NOT handled 
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UnhiliteMenu 
; PROCEDURE HiLiteMenu (menuID: INTEGER); 
CLR - (SP) ; All Menus 
HiLiteMenu ; UnHilite Them Ail 
ETS 
=m Misc Routines--------------------------- 
About 


; Call GetNewDialog to read the dialog box parameters from the resource file 
; and display the box. Set the rt to the box, then wait for the proper 


; click or keypress. Finally, close the dialog box and set the pointer to us. 


; FUNCTION GetNewDialog (dialogID: INTEGER; dStorage: Ptr; 


: behind: WindowPtr) : DialogPtr 
CLR.L - (SP) ; Space For dialog pointer 
MOVE #About Dialog, - (SP) ; Identify dialog rsrc # 
PEA DStorage ; Storage area 
MOVE.L &-1,-(SP) ; Dialog goes on top 
GetNewDialog ; Display dialog box 
MOVE.L (SP), - (SP) ; Copy handle for Close 
; PROCEDURE SetPort (gp: GrafPort); Handle already on stack 
_SetPort ; Make dialog box the port 
; PROCEDURE TEDeActivate (hTE: TEHandle) 
MOVE.L TextHReg, - (SP) ; Identify Text 
_TEDeActivate ; Deactivate Text 

WaitOK 
: PROCEDURE ModalDialog (filterProc: ProcPtr; 
; VAR itemHit: INTEGER}; 
CLR.L - (SP) ; Clear space For handle 
PEA ItemHit ; Storage for item hit 
_ModalDialog ; Wait for a response 
MOVE ItemHit,DO ; Look to 9ee what was hit 
CMP #ButtonItem, DO ; was it OR? 
BNE WaitOK ; No, wait for OK 


; PROCEDURE CloseDialog (theDialog: DialogPtr); 
CloseDialog ; Handle already on stack 
BRA GoSetOurPort `; Set port to us and return 


u 
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a 
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ET Te Data Starts Here ------------------------- 


EventRecord ; NextEvent’s Record 

What: DC Q ; Event number 

Message: DC.L Q ; Additional information 
When: DC.L 0 ; Time event was posted 
Point: DC.L 0 ; Mouse coordinates 
Modify: DC 0 ; State of keys and button 
WWindow: DC.L 0 ¿ Find Window’s Result 
DStorage DCB.W DWindLen, 0 ; Storage For Dialog 
DeskName DCB.W 16,0 ; Desk Accessory's Name 
Bounds DC 28,4,308,508 ; Drag Window's Bounds 
ViewRect DC 5,4,245,405 ; Text Record's View Rect 
DestRect DC 5,4,245,405 ; Text Record's Dest Rect 
ItemHit DC 0 ; Item clicked in dialog 
Pp———————————-------------- Nonrelocatable Storage ----------------------- 


; Variables declared using DS are placed in a global space relative to 
; AS. When these variables are referenced, AS must be explicitly mentioned. 


WindowStorage DS.W WindowSize ; Storage for Window 
End 


116 Macintosh 68000 Development System 


————————— ya — 
The Program's Resource File 


* 
: This is the resource file for the example program called "Window" 


MDS2:Window.Rsrc 


MENU Resource #1 specifies the menus used by the Window program. 

For proper support of the Desk accessories, the Apple menu 

should be first, and the Edit menu should be third. The first 5 items 
in the Edit menu should be identical to those used below. This makes 
it possible for the desk accessories to share the Edit menu with your 
application. 


+ > W + Yf +> + 


Type MENU 


\14 
About This Example... 
(- 


rå 
File 
Quit 


ra 

Edit 
ee 
ee 
Copy 
Paste/V 
Clear 


* Dialog Resource #1 specifies properties of the About box. It points 
* to Dialog Item List (DITL} Resource #1 as containing its items. 


Type DLOG 
: 


100 100 190 400 
Visible NoGoAway 


1 — 
0 
1 
* Dialog Item List Resource #1 specifies the items in the About box. 
* By convention, the first item in an item list is the OK button. 
* I£ there is a cancel button, it should be second. This makes it 
* easler to interpret the item number returned by the call to ModalDialog. 
Type DITL 
så 
Button 
60 230 80 290 
OK 
StaticText 


15 20 36 300 
This sample program was written 


StaticText 
35 20 56 300 
just to prove it could be done! 
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* WIND Resource #1 specifies the titla, coordinates, and other status 
* for the window in which editing takes place. It is displayed by a 
* call to GetNewWindow. 


Type WIND 

¿A 
A Sample 
50 40 300 450 
Visible NoGoAway 
0 


0 
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System Traps 
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EE A A A TE 
System Traps: Sorted by Name 


Here is an alphabetically sorted list of the Toolbox and Operating 
System traps and their trap numbers in hexadecimal. 


Make sure the names you use are the same as the names given here. Trap 
names that differ when used from Pascal are marked by an asterisk. 


AddDrive SAAE ClosePort $A87D 
Add Pt $A87E CloseResFile $A99A 
AddReference SA9AC CloseRgn $A8DB 
AddResMenu SA94D CloseWindow $A92D 
AddResource $A9AB CmpString SAØ3C 
Alert $A985 ColorBit SAB64 
Allocate $AØ1Ø CompactMem SAPAC 
AngleFromSlope $A8C4 Control $A094 
AppendMenu $A933 CopyBits SA8EC 
BackColor $A863 CopyRgn SABDC 
BackPat $A87C CouldAlert $A989 
BeginUpdate $A922 CouldDialog $A979 
Bit And $A858 CountMItems $A950 
BitClr SA85F Count Resources SA99C 
BitNot SA85A CountTypes SA99E 
BitOr SA85B Create SAØØS 
BitSet SAB5E CreateResFile SA9B1 
BitShift SAB5C CurResFile $A994 
BitTst SABSD Date2Secs SA9C7 
BitXOr $4859 Delay $AØ3B 
BlockMove SAME Delete SAØØS 
BringToFront $A929 De let eMenu $A936 
Button $A974 DeltaPoint $A94F 
CalcMenuSize $A948 Dequeue SA96E 
CalcVBehind $A90A DetachResource $4992 
CalcVis $4999 DialogSelect $4980 
CautionAlert $A988 DiffRgn $ABE6 
Chain $A9F3 DisableItem $A93A 
ChangedResData $A9AA DisposControl $4955 
CharWidth SABBD DisposDialog $A983 
CheckItem $A945 DisposeMenu $A932 
CheckUpdate $A911 DisposHandle $AØ23 
ClearMenuBar $A934 DisposPtr SAØLF 
ClipAbove $A90B DisposRgn $A8D9 
ClipRect $A87B DisposWindow $A914 
Close SAØØL DragControl $A967 
CloseDeskAcc $4987 DragGrayRgn $A905 
CloseDialog $4982 DragTheRgn $4926 
ClosePgon $A8CC DragWindow $A925 
ClosePicture SA8F4 DrawChar $A883 
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DrawControls 
DrawDialog 
DrawGrowIcon 
DrawMenuBar 
DrawNew 
DrawPicture 
DrawString 
DrawText 
DrvrInstall 
DrvrRemove 
Eject 
EmptyHandle 
EmptyRect 
EmptyRgn 
EnableItem 
EndUpdate 
Enqueue 
EqualPt 
EqualRect 
EqualRgn 
EraseArc 
EraseOval 
ErasePoly 
EraseRect 
EraseRgn 
EraseRoundRect 
ErrorSound 
EventAvail 
ExitToShell 
FillAre 
FillOval 
FillPoly 
FillRect 
FillRgn 
FillRoundRect 
FindControl 
FindWindow 
FixMul 
FixRatio 
FixRound 
FlashMenuBar 
FlushEvents 
FlushFile 
FlushVol 
FMSwapFont 
ForeColor 
Frame Årc 
FrameOval 
Frame Poly 
FrameRect 
FrameRgn 
FrameRoundRect 


$A969 
$A981 
SA9Ø4 
$A937 
SASØF 
SA8F6 
$A884 
SA885 
$A03D 


SAQ3E * 


$A017 
SAØ2B 
SABAE 
SABE2 
$A939 
$A923 
$A96F 
54881 
$A8A6 
SA8E3 
SA8CÓ 
$A8B9 
$A8C8 
SABA3 
$A8D4 
$A8B2 
$A98C 
$A971 
SA9F4 
$A8C2 
SA8BB 
SA8CA 
$A8A5 
$A8D6 
SA8B4 
$A96C 
$A92C 
$A868 
$A869 
SA86C 
$A94C 
$4032 
SA045 
$AØ13 
$4901 
$A862 
SABBE 
$ABB7 
5A8C6 
SABAL 
SABD2 
SABBØ 


+ 


FreeAlert 
FreeDialog 
FreeMen 
FrontWindow 
GetAppParms 
GetClip 
GetCRefCon 
GetCTitle 
GetCtlAction 
GetCtlValue 
GetCursor 
GetDIten 
GetEOF 
GetFilelnfo 
GetFName 

Get FNum 
GetFontInfo 
GetFPos 
GetHandleSize 
GetIcon 
GetIndResource 
GetIndType 
Get Item 
Get I Text 
GetItmIcon 
Get [tmMark 
GetItmStyle 
GetKeys 
GetMaxCt1 
GetMenuBar 
GetMHandle 
GetMinCtl 
GetMouse 
GetNamedResource 
GetNewControl 
GetNewDialog 
GetNewMBar 
GetNewWindow 
GetNextEvent 
GetOSEvent 
GetPattern 
GetPen 
GetPenState 
GetPícture 
GetPixel 
GetPort 
GetPtrSize 
GetResAttrs 
GetResFileåttrs 
GetRes Info 
GetResource 
Get RMenu 


SA98A 
SA97A 
SAQ1C 
$A924 
SA9F5 
SA87A 
$A95A 
$A95E 
SA96A 
$A96Ø 
$A9B9 
$A98D 
$AQ11 
SAØØC 
SASFF 
$A900 
$A88B 
$A018 
$4025 
$A9BB 
SA99D 
$A99F 
SA946 
5A990 
$A93F 
$A943 
$A941 
$4976 
$A962 
$A93B 
$A949 
$A961 
$A972 
$A9A] 
SA9BE 
$A97C 
$A9CÓ 
SA9BD 
$4976 
$4931 
$A9B8 
SA89A 
$A898 
$A9BC 
$A865 
54874 
SAØ21 
SA9A6 
SA9F6 
$A9A8 
$A9AQ 


+ 


* 


SA9BF * 


TE BE. UE je Ü. sú. I 05 8 0 8 8 19 — IW Ww TW 8 Iw 6 8 7 818: 


LE 


GetScrap 
GetString 
GetTrapAddress 
GetVol 
Get Vol Info 
GetWindowPic 
GetWMgrPort 
GetWRefCon 
GetWTitle 
GetZone 
GlobalToLocal 
GrafDevice 
GrowWindow 
Hand AndHand 
Hand 1leZone 
Hand ToHand 
HideControl 
HideCursor 
HidePen 
HideWindow 
HiliteControl 
HiliteMenu 
HiliteWindow 
HiWord 

HLock 

HNo Purge 
Home ResFile 
HPurge 
HUnlock 
InfoScrap 
InitAllPacks 
InitApplZone 
InitCursor 
InitDialogs 
InitFonts 
InitGraf 
InitMenus 
InitPack 
InitPort 
InitQueue 
InitResources 
InitUtil 
InitWindows 
InitZone 
InsertMenu 
Insert ResMenu 
InsetRect 
InsetRgn 
InvalRect 
InvalRgn 
InverRect 
InverRgn 


SAIFD 
SA9BA 
$AG46 
SAØLG 
SAØØ? 
$A92F 
$4910 
$A917 
$4919 
SAØLA 
SA871 
$A872 
$A92B 
SA9E4 
$AØ26 
SAYEL 
$A958 
54852 
54896 
$A916 
$A95D 
$A938 
SA91C 
$AB6A 
SAQ29 
SAG4A 
SAYA4 
$AØ49 
SAQ2A 
$A9F9 
SA9E6 
SAB2C 
$A85¢ 
$A97B 
SASFE 
SA86E 
$4936 
SA9ES 
SA86D 
SA916 
$A995 
SAQ3F 
$4912 
SA019 
$A935 
$4951 
$A8A9 
SABEL 
$A928 
$A927 


SA8A4 * 
SA8D5 * 


InverRoundRect 
InvertArc 
Invert Oval 
Invert Poly 
IsDialogEvent 
KillControls 
KillIO 
KillPicture 
KillPoly 
Launch 

Line 

LineTo 
LoadResource 
LoadSeg 
LocalToGlobal 
LodeScrap 
LongMul 
LoWord 
MapPoly 
MapPt 
MapRect 
MapRgn 
MaxMem 
MenuKey 
MenuSelect 
ModalDialog 
MoreMasters 
MountVol 
Move 
MoveControl 
MovePortTo 
MoveTo 
MoveWindow 
Munger 
NewControl 
NewDialog 
NewHandle 
NewMenu 
NewPtr 
NewRgn 
NewString 
NewWindow 
NoteAlert 
ObscureCursor 
Offline 
Offset Poly 
OffsetRect 
OfsetRgn 
Open 
OpenDeskAcc 
OpenPicture 
OpenPoly 
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SA8B3 * 


$A8C1 
SA8BA 
$A8C9 
$A97F 
$4956 


SAØØG * 


SABFS 
SA8CD 
SA9F2 
$A892 
SA891 
$A9A2 
$A9FÓ 
$A879 


SA9FB * 


$A867 
$A86B 
SA8FC 
SABF9 
SABFA 
SA8FB 
SAØLD 
$A93E 
$A93D 
$A99] 
SAG36 
SAØØF 
$A894 
$A959 
$A877 
$A893 
SA91B 
SAIED 
$A954 
SA97D 
SAp22 
$4931 
SAØLE 
SA8D8 
$A9Ø6 
$A913 
$A987 
$A856 
SAØ3S 
SABCE 
$ABAB8 
SABER 
SAPA 
$A9B6 
SA8F3 
SA8CB 
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OpenPort 
OpenResFile 
OpenRF 
OpenRgn 
OSEventAvail 
Pack 

Packi 

Pack2 

Pack3 

Pack4 

Pack5 

Pack6 

Pack? 
PackBits 
PaintArc 
Paint Behind 
Paint One 
PaintOval 
Paint Poly 
PaintRect 
Paint Rgn 
Paint RoundRect 
ParamText 
PenMode 

Pen Normal 
PenPat 
PenSize 
PicComment 
PinRect 

Plot Icon 
Port Size 
PostEvent 
Pt2Rect 
PtInRect 
PtInRgn 
PtrAndHand 
Pt rToHand 
PtrToXHand 
PtrZone 
PtToAngle 
PurgeMen 
PutScrap 
Random 
RDrvrinstall 
Read 
ReadDateTime 
RealFont 
ReallocHandle 
RecoverHandle 
RectInRgn 
Rect Rgn 
ReleaseResource 


$A86F 
$A997 
SAØØA 
$A8DA 
SA930 
$A9E7 
SA9E8 
SA9E9 
$A9EA 
$A9EB 
SAIEC 
SA9ED 
SA9EE 
SASCF 
$ASBF 
SASØD 
$A99C 
$ABBB 
$A8C7 
$A8A2 
SA8D3 
$A8B1 
$A98B 
$A89C 
SA89E 
$A89D 
$A89B 
$A8F2 
$A94E 
SA94B 
$A876 
SAQ2F 
SABAC 
$ASAD 
$A8E8 
S$A9EF 
$A9E3 
$A9E2 
$4948 
$A8C3 
$AØ4D 
$A9FE 
$A861 
SAQAF 
$AØØ2 
$A939 
$4902 
$4027 
$4928 
SA8E9 
SA8DF 
SA9A3 


* 


Rename 
ResError 
ResrvMem 
RmveReference 
RnveResource 
RsrcZoneInit 
RstFilLock 
SaveOld 
ScalePt 
ScrollRect 
Secs2Date 
SectRect 
SectRgn 
SelectWindow 
SellText 
Send Behínd 
Set App Base 
SetApplLimit 
SetClip 
SetCRe fCon 
SetCTitle 
SetCtlAction 
SerCt I Value 
SetCursor 
Set DateTine 
Set DItem 

Set EmptyRgn 
Set EOF 

Set File Info 
SetFilLock 
Set FilType 
Set Font Lock 
Set FPos 

Se tGrowZone 
SetHandleSize 
Set Item 

Set IText 

Set ItmIcon 
Set ItmMark 
Set ItmStyle 
SetMaxCtl 
SetMenuBar 
SecMFlash 
SetMinCtl 
SetOrigin 
SetPBits 
SetPenState 
SetPort 
SetPt 
SetPtrSize 
SetRecRgn 
SetRect 


SAØØB * 


$A9AF 
$A049 
SA9AE 
SAIAD 
$4996 
$AØ42 
$A9PE 
$A8BF8 
SABEF 
$A9C6 
SABAA 
$A8EA 
$A91F 
$A97E 
$4921 
$A857 
SAQ2D 
$A879 
$A95B 
$A95F 
$A96B 
$4963 
$A851 
SAG3A 
$A98E 
$A8DD 
$4012 
$A00D 
SAG41 
$AØ4 3 
$A9Ø3 
SAB44 
$AØ4B 
$AØ24 
$A947 
$A98F 
$A94Ø 
$A944 
$A942 
$4965 
$A93C 
SA94A 
$A964 
$A878 
$A875 
$A899 
$4873 
$A880 
SAp24 
SABDE 
$ABA7 


* * * + * + + >» * 


* 


SetResAttrs 
SetResFileAttrs 
SetResInfo 
Set Res Load 
SetRes Purge 
SetStdProcs 
SetString 
SetTrapAddress 
SetVol 
SetWindowPic 
Se tWRefCon 
SetWTitle 
Set Zone 
ShieldCursor 
ShowControl 
ShowCursor 
ShowHide 
ShowPen 
ShowWindow 
SizeControl 
SizeResource 
SizeWindow 
SlopeFromAngle 
SpaceExtra 
Status 
Stdårc 
StdBits 
StdComment 
StdGet Pic 
StdLine 
StdOval 
StdPoly 
StdPurPic 
StdRect 
StdRgn 
StdRRect 
StdText 
StdTxMeas 
StillDown 
StopAlert 
StringWidth 
StuffHex 


«SubPt 


SysBeep 
SysEdit 
SysError 
SystemClick 
SystemEvent 
SystemMenu 
SystemTask 


SA9A7 
$A9F7 
$A9A9 
$A99B 
$A993 
SABEA 
$4997 
$A047 
$A815 
$A92E 
$A918 
SA9IA 
SAQ1B 
SAB55 
$A957 
$4853 
$A998 
$A897 
$4915 
SA95C 
SA9A5 
$A91D 
SA8BC 
SA88E 
$A005 
SA8BD 
SASEB 
$ABFI 
SABEE 
SA89G 
$A8B6 
$A8C5 
SASFØ 
SABAØ 
SABDI 
SASAF 
$A882 
SA8ED 
$A973 
$A986 
$A88C 
$ A866 
SA87F 
SA9C8 
SA9C2 
$A9C9 
$A9B3 
$A9B2 
$A9B5 
SA9 B4 
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TEActivate 
TECal Text 
TEClick 
TECopy 
TECut 
TEDeactivate 
TEDelete 
TEDispose 
TEGet Text 
TEIdle 
TEInit 
TEInsert 
TEKey 

TENew 
TEPaste 
TEScroll 
TESet Just 
TESet Select 
TESet Text 
TestControl 
TEUpdate 
Text Box 
TextFace 
Text Font 
TextMode 
Text Size 
TextWidth 
TickCount 
TrackControl 
TrackGoAway 
UnionRect 
UnionRgn 
Unique ID 
UnloadSeg 
UnlodeScrap 
UnmountVol 
UnpackBits 
UpdateResFile 
UprString 
UseResFile 
ValidRect 
ValidRgn 
Vinstall 
VRemove 
WaitMouseUp 
Write 
WriteParam 
WriteResource 
XOrRgn 
ZeroScrap 


$A9D8 
$A9DØ 
$ A9D4 
$A9D5 
$A9D6 
$A9D9 
$A9D7 
$A9CD 
$A9CB 
$A9DA 
SAICC 
$A9DE 
$A9DC 
$A9D2 
$A9DB 
SA9DD 
SA9DF 
$A9D1 
SA9CF 
$A966 
$A9DJ3 
SA9CE 
$ A888 
$A887 
$A889 
$A88A 
$A886 
$A975 
SA968 
SA91E 
SABAB 
SABES 
SAIC] 
SA9F1 
SASFA 
$AØØE 
$A8DÓ 
$4999 
5A854 
$A998 
$A92A 
54929 
$AØ33 
SAQ034 
$A977 
$A093 
$4038 
$ A9B0 
SABE7 
SA9FC 


125 


126 


Macintosh 68000 Development System 


System Traps: Sorted by Number 


Here is an alphabetically sorted list of the Toolbox and Operating 
System traps, and their trap numbers in hexadecimal. 


Make sure the names you use are the same as the names given here. Trap 
names that differ when used from Pascal are marked by an asterisk. 


$AØØØ 
SAØØL 
$AØØ2 
$AØØ3 
SAB04 
SAPOS 
$ A006 
SADO? 
$AØØS 
$ A@09 
SAØØA 
SAØØB 
$SAØØC 
SAØØD 
SAØØE 
SAØØF 
SAØLØ 
$AG11 
$AG12 
$AG13 
SAG14 
$A015 
SAQ16 
$A017 
$A918 
$Aß19 
SABIA 
SAØLB 
$ABIC 
SAØLD 
$AQ1E 
SAØLF 
SAP2P 
$AØ21 
$AØ22 
$AØ23 
$AØ24 
$AØ25 
$AØ26 
$A027 


Open 

Close 

Read 

Write 
Control 
Status 
K1111IO 
GetVolinfo 
Create 
Delete 
OpenRF 
Rename 
GetFilelnfo 
SetFilelnfo 
UnmountVol 
Mount Vol 
Allocate 

Get EOF 
SetEOF 
FlushVol 

Get Vol 

Set Vol 
InitQueue 
Eject 
GetFPos 
InitZone 

Get Zone 

Set Zone 
FreeMen 
MaxMem 
NewPtr 
DisposPtr 
SetPtrSíze 
GetPtrSize 
NewHandle 
DisposHandle 
SetHandleSize 
GetHandleSize 
HandleZone 
ReallocHandle 


> + * + Box So» HF 


++ * * +* * * * + *+ * * 


* 


$A028 
$AØ29 
SAØ2ZA 
$AØ2B 
SAB2C 
$AØ2D 
$AQ2E 
SAØ2F 
SAB30 
SA031 
$AØ32 
$AØ33 
$AØ34 
SAØ35 
$AØ36 
$AØ38 
$AØ39 
SAØ3A 
$AØ3B 
SAP3C 
SAP3D 
SAQ3E 
SABIF 
SAG4G 
$AØ4 1 
$AØ42 
$AØ43 
SAG44 
$AØ45 
$AØ46 
$A047 
$AØ48 
$AG49 
SAØSA 
SAG4B 
SAG4C 
SAG4D 
SAQAE 
SAQAF 
$A850 


RecoverHandle 
HLock 

HUnlock 
EmptyHandle 
InitApplZone 
SetApplLimit 
BlockMove 
PostEvent 
OSEventAvail 

Get OSEvent 
FlushEvents 
VInstall 

VRemove 

Offline * 
MoreMasters 
WriteParam 
ReadDateTime 
SetDateTime 
Delay 

CmpString * 
DrvrInstall 
DrvrRemove 
InitUtil 
ResrvMem 
SetFilLock 

Ret FilLock 
SetFilType 
SetFPos 
FlushFile 
GetTrapAddress 
SetTrapAddress 
PtrZone 

HPurge 
HNoPurge 

Se tGrowZone 
Compact Mem 
PurgeMem 
AddDrive 
RDrvrInstall 
InitCursor 


* * 


+ +f A + * 


mr w Iw w t Www IY V 


"m nm m 


m 


v 


n" mo gn gw mom ow 


n 


$A851 
$A852 
$A853 
$A854 
$A855 
$A856 
$A857 
$A858 
$A859 
SAB5A 
SABSB 
$A85C 
$A85D 
SABSE 
SA85F 
SAB61 
$A862 
$A863 
$A864 
$A865 
$A866 
$A867 
$A868 
$A869 
$AB6A 
$A86B 
SA86C 
$A86D 
SA86E 
SA86F 
SA870 
$A871 
$A872 
$A873 
$A874 
$A875 
$A876 
$A877 
$4878 
$A879 
SA87A 
$A87B 
. SAB7C 
$A87D 
SA87E 
$A87F 
SA886 
$A881 
$A882 
$A883 
$A884 
$A885 


SetCursor 
HideCursor 
ShowCursor 
UprString 
ShieldCursor 
ObscureCursor 
Set AppBase 
Bit And 

Bit XOr 
BitNot 
BitOr 
BitShift 
BitTst 
BitSet 
BitClr 
Random 
ForeColor 
BackColor 
ColorBit 
Get Pixel 
Stuf fHex 
LongMul 
FixMul 
FixRatio 
HiWord 
LoWord 
FixRound 
Init Port 
InitGraf 
OpenPort 
Local ToGlobal 
Global ToLocal 
GrafDevice 
SetPort 
GetPort 
SetPBíts 
PortSize 
MovePortTo 
SetOrigin 
SetClip 
GetClip 
ClipRect 
BackPat 
ClosePort 
AddPt 
SubPt 
SetPt 
EqualPt 
StdText 
DrawChar 
DrawString 
DrawText 


$A886 
$4887 
$A888 
$A889 
SA8BA 
$A88B 
$AB8C 
$ A88D 
SA88E 
SAS9Ø 
$A891 
$A892 
$A893 
$A894 
$A896 
$A897 
$A898 
$A899 
$A89A 
SA89B 
$A89C 
$A89D 
SAB9E 
SABAG 
SABAL 
$A8A2 
SABA3 
SA8A4 
$A8A5 
$A8A6 
$A8A7 
$ABAB 
$ABA9 
SABAA 
SASAB 
SABAC 
SABAD 
SABAE 
SABAF 
SABBÓO 
SA8B1 
SA8B2 
$A8B3 
SA8B4 
SA8B6 
$A8B7 
$48B8 
SA8B9 
SASBA 
$A8BB 
$A88C 
SASBD 
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TextWidth 

Text Font 

Text Face 

Text Mode 

Text Size 

Get Font Info 
StringWidth 
CharWidth 
SpaceExtra 
StdLine 

LineTo 

Line 

Move To 

Move 

Hide Pen 
ShowPen 

Get PenState 
Set PenState 
Get Pen 

PenSize 
PenMode 

PenPat 
PenNormal 
StdRect 
FrameRect 
PaintRect 
EraseRect 
InverRect * 
FillRect 
EqualRect 
SetRect 
OffsetRect 
InsetRect 
SectRect 
UnionRect 
Pt2Rect 
PtInRect 
EmptyRect 
StdRRect 

Frame RoundRect 
PaintRoundRect 
Erase RoundRect 
InverRoundRect * 
FillRoundRect 
StdOval 
FrameOval 
PaintOvai 
EraseOval 
InvertOval 
FillOval 
SiopeFromAngle 
Stdárc 


128 


SASBE 
$ASBF 
$ABCØ 
$A8CI 
$A8C2 
$A8C3 
5A8C4 
$A8C5 
$A8C6 
$A8C7 
$A8C8 
$ABC9 
SABCA 
$A8CB 
$ABCC 
SA8CD 
$ASCE 
SA8CF 
$A8DØ 
$A8D1 
$ABD2 
$A8D3 
$A8D4 
SABDS 
$A8D6 
$A8D8 
$A8D9 
$A8DA 
$ABDB 
$ABDC 
$A8DD 
SABDE 
SA8DF 
SABEØ 
SABEL 
SA8E2 
SASE3 
$A8E4 
SABES 
$ABE6 
SA8E7 
$A8E8 
SA8E9 
SA8EA 
SABEB 
$ABEC 
$A8ED 
SASEE 
SASEF 
$ASFØ 
SA8F1 
SABF2 
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FrameArc 
PaintAre 
EraseArc 
InvertAre 
FillArc 
PtToAngle 
AngleFromSlope 
StdPoly 
FramePoly 
PaintPoly 
ErasePoly 
InvertPoly 
FillPoly 
OpenPoly 
ClosePgon * 
KiliPoly 
OffsetPoly 
PackBits 
UnpackBits 
StdRgn 
FrameRgn 
PaintRgn 
EraseRgn 
InverRgn * 
FillRgn 
NewRgn 
DisposRgn 
OpenRgn 
CloseRgn 
Copy Rgn 
SetEmptyRgn 
SetRecRgn 
RectRgn 
OfsetRgn * 
InsetRgn 
EmptyRgn 
EqualRgn 
SectRgn 
UnionRgn 
DiffRgn 

XOrRgn 

Pt InRgn 

Rect InRgn 
SetStdProcs 
StdBits 

Copy Bíts 
StdTxMeas 
StdGetPic 
ScrollRect 
StdPutPic 
ScdComment 
PicComment 


* 


$ABF3 
SASF4 
SA8F5 
SA8F6 
SASF8 
$ABF9 
SASFA 
SABFB 
SABFC 
SASFE 
SASFF 
$4909 
$A991 
$A902 
$4993 
SA9P4 
$A905 
$4946 
$A907 
$A9Ø8 
5A999 
SAIGA 
SA9PB 
$A9ØC 
$A9ØD 
SASØE 
SA9PF 
$A919 
$A911 
$4912 
$A913 
$A914 
$A915 
$4916 
$A917 
$4918 
$A919 
SA91A 
$A91B 
$A91C 
$A91D 
$A91E 
$A91F 
$4920 
$4921 
$A922 
$A923 
$4924 
$4925 
$A926 
$A927 
$A928 


OpenPicture 
ClosePicture 
KillPicture 
DrawPicture 
ScalePt 
MapPt 
MapRect 
MapRgn 
MapPoly 
InitFonts 
Get FName 

Get FNum 
FMSwapFont 
RealFont 
SetFontLock 
DrawGrowIcon 
DragGrayRgn 
NewString 
SetStríng 
ShowHide 
CalcVis 
CalcVBehind 
ClipAbove 
PaintOne 
PaintBehind 
SaveOld 
DrawNew 
GetWMgrPort 
CheckUpdate 
InítWindows 
NewWindow 
DisposWindow 
ShowWindow 
HideWindow 
GetWRefCon 
SetWRefCon 
GetWTitle 
SetWTitle 
MoveWindow 
HiliteWindow 
SizeWindow 
TrackGoAway 
SelectWindow 
BringToFront 
Send Behind 
BeginUpdate 
End Update 
FrontWindow 
DragWindow 
Drag TheRgn 
InvalRgn 
InvalRect 


$4929 
$A92A 
$A92B 
$A92C 
$A92D 
$A92E 
$A92F 
$4939 
$4931 
$A932 
$A933 
$A934 
$4935 
$A936 
$A937 
$4938 
$4939 
$A93A 
$A93B 
$A93C 
$A93D 
$A93E 
$A93F 
$4940 
$A941 
$A942 
$4943 
$A944 
$A945 
$A946 
$A947 
$A948 
$A949 
$A94A 
$A94B 
$A94C 
$A94D 
SA94E 
$A94F 
$4959 
$A951 
$A954 
$A955 
$A956 
$4957 
$A958 
$4959 
$A95A 
$A95B 
$A95C 
$A95D 
SA95E 


ValidRgn 
ValidRect 
GrowWindow 
FindWindow 
CloseWindow 
SetWindowPic 
GetWindowPic 
InitMenus 
NewMenu 
DisposeMenu 
AppendMenu 
ClearMenuBar 
InsertMenu 
DeleteMenu 
DrawMenuBar 
HititeMenu 
Enable ltem 
Disableltem 
GetMenuBar 
SetMenuBar 
MenuSelect 
MenuKey 
GetItalcon 
SetItmIcon 
Get ItmStyle 
Set ItmStyle 
Get ItmMark 
Set ItmMark 
CheckItem 
GetItem 

Set Item 
CalcMenuSize 
GetMHandle 
SetMFlash 
PlotIcon 
FlashMenuBar 
AddResMenu 
PinRect 
DeltaPoint 
CountMItems 
Insert ResMenu 
NewControl 
DisposControl 
KíllControls 
ShowControl 
HideControl 
MoveControl 
GetCRefCon 
SetCRefCon 
SizeControl 
HiliteControl 
GetCTitle 
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$A95F 
$A96Ø 
$A961 
$A962 
$4963 
$A964 
$4965 
$4966 
$A967 
$A968 
$A969 
$A96A 
$A96B 
$A96C 
$A96E 
$A96F 
$4970 
$4971 
$A972 
$A973 
$A974 
$A975 
$A976 
$A977 
$A979 
SA97A 
SA97B 
$A97C 
$A97D 
$A97E 
$A97F 
$A980 
$4981 
$4982 
$4983 
$4985 
$A986 
$A987 
$A988 
$4989 
$A98A 
$A98B 
$A98C 
$A98D 
SA98E 
$A98F 
$4996 
$4991 
54992 
$A993 
$A994 
$A995 
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SetCTitle 
GetCtlValue 
GetMinCt1 * 
GetMaxCtl * 
SetCtl Value 
SetMinCtl * 
SetMaxCtl * 
TestControl 
DragControl 
TrackControl 
DrawControls 
GetCtlAction 
SetCtlAction 
FindControl 
Dequeue 
Enqueue 
GetNextEvent 
EventAvail 
GetMouse 
StillDown 
Button 
TickCount 
GetKeys 
WaitMouseUp 
CouldDialog 
FreeDialog 
InitDialogs 
GetNewDialog 
NewDialog 
SeilText 
IsDialogEvent 
DialogSelect 
DrawDialog 
CloseDialog 
Dispos Dialog 
Alert 
StopAlert 
NoteAlert 
CautionAlert 
CouldAlert 
FreeAlert 
ParamText 
Error Sound 
GetDItem 
SetDItem 
SetiText 
GetIText 
ModaiDialog 
DetachResource 
SetRes Purge 
CurResFile 
Init Resources 
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$A996 
$4997 
$A998 
$A999 
$A99A 
SA99B 
$A99C 
$A99D 
$A99E 
$A99F 
$A9AQ 
$A9AI 
$A9A2 
$A9A3 
SAGA4 
$A9A5 
SA9A6 
$A9A7 
$A9AB8 
$A9A9 
$A9AA 
SA9AB 
$A9AC 
SA9AD 
SA9AE 
SA9AF 
SA9BØ 
$A9B1 
$A9B2 
$A9B3 
SA9B4 
$ A9B5 
SA9B6 
$A9B7 
$A9B8 
SA9B9 
$A9BA 
SA9BB 
$A9BC 
SA9BD 
SA9BE 
SAIBF 
SAICH 
$A9C1 
SA9C2 
$A9C6 
$A9C7 
$A9C8 
$A9C9 
$A9CB 
$A9CC 


RsrcZone Init 
OpenResFile 
UseResFile 
UpdateResFile 
CloseResFile 
SetRes Load 
Count Resources 
Get IndResource 
CountTypes 
GetIndType 
GetResource 
GetNamedResource 
LoadResource 
Release Resource 
HomeResFile 
SizeResource 
GetResAttrs 
SetResAttrs 
GetResInfo 
SetResinfo 
ChangedResData 
AddResource 
AddReference 
RmveResource 
RmveReference 
ResError 
WriteResource 
CreateResFile 
SystemEvent 
SystemClick 
SystemTask 
SystemMenu 
OpenDeskAcc 
CloseDeskAcc 
GetPattern 
GetCursor 
GetString 
GetIcon 
GetPicture 
GetNewWindow 
GetNewControl 
GetRMenu * 
GetNewMBar 
UniqueID 
SysEdit * 
Secs2Date 
Date2Secs 

Sys Beep 
SysError 

TEGet Text 
TEInit 
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SAICD 
SA9CE 
$ A9CF 
$A9DØ 
$A9D1 
$A9D2 
$A9D3 
$A9D4 
$A9D5 
$A9D6 
$A9D7 
$A9D8 
$A9D9 
SA9DA 
$A9DB 
$A9DC 
SAIDD 
$A9DE 
S$A9DF 
SA9EQ 
SA9El 
$A9E2 
$A9E3 
SA9E4 
$A9E5 
$A9E6 
$A9E7 
$A9E8 
SA9E9 
SASEA 
SA9EB 
$A9EC 
SA9ED 
SA9EE 
SA9EF 
SA9rQ 
$A9F1 
SA9F2 
SA9F3 
$A9F4 
SA9F5 
SA9F6 
SA9F7 
SA9F9 
SA9FA 
SA9FB 
SA9FC 
$A9FD 
SA9FE 
SA9FF 


TEDispose 
Text Box 
TESetText 
TECal Text 
TESetSelect 
TENew 
TEUpdate 
TEClick 
TECopy 

TECut 
TEDelete 
TEActivate 
TEDeactivate 
TEIdle 
TEPaste 
TEKey 
TEScroll 
TEInsert 
TESet Just 
Munger 

Hand ToHand 
PtrToXHand 
Ptr ToHand 
Hand AndHand 
Init Pack 
InitAllPacks 
Pack? 

Pack] 

Pack2 

Pack3 

Packá 

Pack5 

Pack6 

Pack? 
PtrAndHand 
LoadSeg 
UnloadSeg 
Launch 
Chain 
ExitToShell 
Get AppParms 
GetResFileAttrs 
SetResFileAttrs 
InfoScrap 
UnlodeScrap * 
LodeScrap k 
ZeroScrap 
GetScrap 

Put Scrap 
Debugger 


A B 


AA 


tw 
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Error Messages 
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Assembler Error Messages 


Here is 


Assembler. 


a list of the error messages that can be displayed by the 
A brief description accompanies the messages that are not 


entirely self-explanatory. 


Absolute expression required 


Character literal size error: 


Character literals must be from l to 4 


characters long. 


Could not open 

Could not open error file: 

Could not open file: 

Could not open file name list file: Could not open a .Files file. 
Disk full 


Disk I/O error 
Disk write-protected 


ELSE out of context: 


Only occurs in an IF statement. 


Expression must be constant 
Fatal assembly error: 


File name too long: 


The symbol is longer than 252 characters. 


File open error 


Illegal .ALIGN value 

Illegal .DUMP file name 

Illegal expression follows f: For example, DØ. 

Illegal expression operand in EA: The operand used in the effective 
address field is illegal. 

Illegal formal not declared 

Illegal INCLUDE file name 

Illegal index size: For example, 274(AØ,DØ). 

Illegal indexing: For example 23(D9,Dl). 

Illegal line: The Assembler could not recognize the line as anything. 


Often caused by missing semicolon on comment line. 

Illegal number: For example, an octal number with an 8 in ít. 

Illegal opcode name 

Illegal opcode size tag: One of the extensions .B, .W, or .L was not 
used in the proper context. 

Illegal operand 

Illegal operand/operator combination: This is a general error message. 


Caused, for example, by MOVE.L DØ,34(PC). 


Illegal 
Illegal 
Illegal 
Illegal 
Illegal 
Illegal 
Illegal 
Illegal 


operator 

or missing operand(s) for instruction: 
register list 

relocatíon in expression 

RESOURCE directive 
string comparison: 
symbol type: 

trap definition 


For example, PEA Dé. 


Only occurs in an IF statement. 


I/O memory error 
Macro definition error 
Macro too long 


Missing 
Missing 
Missing 


<char> 
ENDIF: Only occurs in an IF statement. 
formal in macro 
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Missing formal in macro definition or call 

Missing nacro definition body 

Missing operand 

Missing operator 

Missing string literal 

Multiply defined label: The specified label was previously declared. 

Multiply defined symbol 

<Name> redefined 

Not enough room for...: Occurs when loading packed symbols. 

Number expected: This message comes from a macro definition. 

Number too long: The symbol is longer than 252 characters. 

Out of memory: Probably symbol table full or MacsBug installed. 

Partial field error in macro formal 

PC relative address out of range: This is usually caused by a short PC 
relative reference backward to a label that is too far away. 

Register list expected 

Size mismatch for operator/operands: The size of the operand does not 
match the size of the operator (plus .B, .W, or ¿Ls 

Stopped by user: Either the Stop button was clicked or Command-period 
was pressed. 

String overflow: The symbol is longer than 252 characters. 

String too long: The symbol is longer than 252 characters. 

Symbol too long: The symbol is longer than 252 characters. 

Too many formals in macro 

Too many levels of macro nesting 

Too many nested files 

Undefined label: 

Unknown cause: This is a serious error of unknown origin. Assembly 
is abandoned when it occurs. 

Unknown directive: Didn't recognize the directive. 

Unknown I/O error 

Unmatched ELSE or ENDIF: Only occurs in an LF statement. 

Value out of range: This is usually caused by a short PC relative 
reference backward to a label that is too far away. 

Volume locked 

Warning: .S operand out of range: .W assumed: This is a warning 
only. 

XREF symbol defíned: This message is a warning only. 


A k 


wm w w w w 


run nm n o A Y 


re ra - rw‘ m’ rw su ‘wr IE A rir 


Linker Error Messages 135 





Linker Error Messages 


Here is a list of the error messages that can be displayed by the 


Linker. 


Code segments cannot follow resources 
Could not create resource 

Could not open file: 

Could not open .Rel file: 

Could not open resource file 

Could not open temp file 

Disk full 

Disk 1/0 error 

Disk write-protected 

Duplicate Ident 
Duplicate symbol 
Error in control 
Errors in linking 
Extra characters on line 
File locked 

File name too long: 
File open error 
Illegal / command 
Illegai input token 
Illegal number 
Illegal .Rel file name 

Illegal starting label 

Illegal symbol Ident 

Invalid or missing .Rel file 

1/0 memory error 

JTSize does not match global size 
JTSize does not match symbol count 
Link errors 

Linker error ... 

Missing Ident 

Multiply defined symbol: 

Not enough memory to create resource: 
Number too long: The symbol is longer than 252 
Out of memory 

RESOURCE directive ín file before /RESOURCES 
Segments cannot follow resources 
Source file open fall: 

Stack overflow 

Stack underflow 

Start label not found: 

Start label undefined 

String overflow 
Symbol too long: 
Symbol not found: 


(System 


file: 


(System 


(System 


(System 
(System 


(System 


(System 
(System 


The symbol ís longer than 252 


Error) 


Unknown type or error message 


The symbol is longer than 252 characters. 


Error) 


Error) 


Error) 
Error) 


Error) 


characters. 


Error) 
Error) 


characters. 


Unknown arith opcode = (System Error) 
Unknown cause 

Unknown I/O error 

Unknown opcode - (System Error) 
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Undefined external: 

Volume locked 

Value or offset out of range: 
Expected a value between xx and yy. 
Actual value was zz. 


RMaker Error Messages 137 


— EEE a Eee Eee ee RAM U 


RMaker Error Messages 


Here is a list of the error messages that can be displayed by RMaker. 
À brief description accompanies the messages that are not entirely 
self-explanatory. 


An Input/Output error has occurred 

Bad attributes parameter 

Bad bundle definition 

Bad format number 

Bad format resource designator in GNRL type: This is any error in 
a user-defined resource type. 

Bad ID Number 

Bad item type 

Bad object definition: This can happen if the specified file is of the 
wrong type. 

Bad type or item declaration 

Can't add to the file -- disk protected or full? 

Can't create the output file 

Can't load INCLUDE file 

Can't open the output file 

Out of memory 

Syntax error ín source fíle 

Unknown type: The specified resource type is not defined. 
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File Naming Conventions 


Name Created by Contents 

Name .Asm Edít Assembler source file 

Name .Files Edit List of separate assemblies to be performed 

Name .Rel Asm Relocatable module with symbol table information 

Name.Lst Asm Assembler listing | 

Name Err Asm Assembly errors 

Name . Sym Asm Symbol table file, generated by .DUMP directive 

Name . D PackSyms Symbol table, used as input to Asm; packed version 
generated by running PackSyms on .Sym files 

Name . Link Edit Files to link; Linker listing on/off; where to 
begin segments, resources, data 

Name Link Application 

Name . LErr Link Errors that occurred during linking 

Name .Map Link Symbol table for MacDB and Linker listing 

Name. Job Edit Executive control program; specifies names of 
applications to be run and files to be passed as 
input to applications 

Name «R Edit RMaker input file; contains resource definitions 

Name .Rsrc RMaker RMaker output file 
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Assembler Quick Reference 


Registers: DØ..D7 


AD..A7 
A7 or SP 
SR 

CCR 

PC 


Data Registers Ø through 7 
Address Registers 9 through 7 
Stack Pointer 

Status Regíster 

Condítion Code Register 
Program Counter 


For MOVEM: '-' for register range; '/' for list. Example: Al-A4/DØ/D6 


Syntax Addressing mode 
An or Dn Register Direct 
(An) Register Indirect 
(An)+ Postincrement Register Indirect 
-( An) Predecrement Register Indirect 
Expr( An) Register Indirect with Offset 
Expr( An , An ) Indexed Register Indirect with Offset 
Expr(An,Dn) Indexed Register Indirect with Offset 
Expr Absolute or Relative 
Expr(PC) Relative with Offset 
Expr(PC,An) Relative with Index and Offset 
Expr(PC,Dn) Relative with Index and Offset 
Expr(Dn) Relative with Index and Offset 
#Expr Immediate 
«B Operands are one byte long 
oW Operands are one word long (2 bytes) 
oL Operands are long words (4 bytes) 
Bec.S Short branch (long is default) 
JMP.W Short jump (long is default) 
Numbers: Decimal is default; $ for hex; ^ for octal; X for binary. 
Strings: Enclosed in single quotes. Use two single quotes in a row to 
put a single quote in a string. 
Symbols: Start with  'A'-'Z', 'a'-'z', ',', ' ' 
Followed by 'A'-'Z', 'a'-'z!, 'Q'-'9', ít "$t, AAT 
Operators: 
Árithmetic Addition * 
Subtraction = 
Multiplication * 
Division / Integer result 
Negation = 
Shift Shift Right >> Zeros shifted in 
Shift Left «< Zeros shifted in 
Logical And & 
! 


Or 
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Precedence: 1. Operations within parentheses (innermost first) 


2. Negation 


3. Shift operations 

4. Logical operations 

5. Multiplication and division 
6. Addition and subtraction 


Assembler Directives: 


INCLUDE filename 
STRING FORMAT value 


General Strings: value = Y 
value = | 
DC.x Strings: value = Ø 
value = 2 
value = 3 


IF condition... ELSE... ENDIF 


MACRO name P1,P2,...Pn = 
XXXX {P1},{P2} 


‘ia {Pn} 
END 
« DUMP 
EQU expression 
SET expression 
REG register list 


.TRAP name $Axxx 
DC.B value(s) 

DC value(s) 
DC.W value(s) 
DC.L value(s) 
DS.B length 

DS length 

DS .W length 

DS.L length 

DCB.B length,value 
DCB length, value 
DCB.W length,value 
DCB.L length,value 
«ALIGN value 


XDEF symbol(s) 

XREF symbol(s) 

RESOURCE type ID [name [attr]] 
«NoList 

J.ListToFile 

«ListToDisp 

« Verbose 


+ NoVerbose 


Include source file 

Set string format 

Text followed by a Ø byte 
Text preceded by a count byte 
Write strings literally 

Text preceded by a count byte 
Specifies 1 and 2 

Conditional assembly 


Mac-style macro definitions. 
Arguments are symbols, defined 
after name» 


End of program 
Dump symbols to .Sym file 
Set permanent constant 
Set temporary constant 
Define register list 
Assign a name to trap number $Axxx 
Define Constant 
values are separated by commas 


Define Storage 


Define Constant Block 


value = 2 for word alignment 
value = 4 for long word alignment 
Symbol used externally 

Symbol defined externally 

Begin resource definition 

Turn off listing 

Turn on listing to file 

Turn on listing to display 

Turn on verbose listing which is 
needed for Linker listing 

Turn off verbose listing 


(v 


ka nt m am m em a m cocum cn cocum o m m . num C RU m z s OUO ü ü SS Ñ wq 90 74 Br 79 Ebo H "SE Ú OR 


(V Ow w wo Ww Ww 


Ly 


Y 


m m m m m m 


I um I I! 16 11 I" IT IT 


IN 


Lj 








Linker Quick Reference 145 


———— ——————— ee", 
Linker Quick Reference 


filename 

! label 

< 

[ 

] 

( 

) 

/Verbose 
/NoVerbose 
/ Unde f OK 
/NoUndef 
/Type 
/Globals 
/Output 

/ Resources 
/Data 

$ 


The next file to link is the file named filename.Rel 


Make 


label the starting locatíon for the program 


Start a new segment 


Turn 
Turn 
Turn 
Turn 
Turn 
Turn 
Give 
Give 


on code listing to .Map file 

off code listing to .Map fíle 

off listing of local labels to .Map file 
on listing of local labels to .Map file 
on verbose linker output 

off verbose linker output 

warning only for undefined symbols 

fatal errors for undefined symbols 


Set type and creator bytes for file 
Set offset from A5 of start of global space 
Specify name of output file 


Code 


section done; begin resource section 


Resource sectíon done; begin data section 
End of Linker control fíle 
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Serial Cable Connections 


These two diagrams illustrate the connections necessary to use MacDB 
with two Macintoshes or with a Macintosh and a Lisa. These allow you 
to build your own cables for use with the Debugger. 


Macintosh to Macintosh Serial Cable 


Mac Serial Port Mac Serial Port 
DB-9 05-9 




















No connect 1 1 No connect 
No connect |2 2 No connect 
Ground 34 | 3 Ground 
TXD+ ¡4 4 TXD+ 
TXD- |5 5 TxD- 

No Connect |6 6 No Connect 
Handshake |7 7 Handshake 
RXD+ |8 8| RxD+ 
RxD- |9 9| RXD- 












Macintosh to Lisa Serial Cable 












Ground 

No connect 
Ground 
TXD+ 
TXD- 

No Connect 
Clock 
RXD+ 
RXD- 


Mac Serial Port 
DB-9 





Lisa Serial Port 
DB-25 


Ground 
TXD 
RXD 


















Ground 


DO y Gs CR + ON — 
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MacsBug Quick Reference 


Numbers: $ means hex; & means decimal. Maximum size is long word 
Text: One to four characters enclosed in single quotes. 
Symbols: RAM. .RA7,RD®..RD7,PC,SP,TP,'.' (dot=current address) 


Operators: + (addition), - (subtraction, negation), @ (indirection) 


Memory Commands 
DM A N Display N bytes of memory starting at address A 
If N = 'IOPB','WIND','TERC', displays data structure 
SM A El..En Set memory values El through En starting at address A 


Register Commands 
Set data register n to E. Tf E is omitted, display n 
Set address register n to E. If E is omitted, display n 
Set the PC to value E. If E is omitted, display the PC 
Set the SR to value E. If E is omitted, display the SR 
Display ali the registers 


32333 
tr pj pj rd 


Control Commands 


BR A C Set breakpoint at address A. Do C times before breaking. 
C is optional 
CL A Clear breakpoint at address A. If A omitted, clear all 
GA Execute application starting at A. If no A, at current PC 
GT A Set one-time breakpoint at address A, start at current PC 
T Trace one instr. Traps treated as single instructions 
SN Step through N instructions. If N is omitted, one 
instruction is executed. Traps not single instructions 
SS Al A2 Remember checksum for address range; step through 


instructions, validating checksum before each one; break 
into MacsBug if checksum changes 

ST A Step through instructions to address A. A can be in ROM 

MR N Execute instructions until return address N bytes down in 
stack is used. If N is omitted, return address on top of 
stack is used 

RB Reboot Macintosh 

ES Exit to the shell; launch startup application 


A-Trap Commands 
Take effect if a trap in the range T1 through T2 is called from address 
range Al through A2, and D@ has a value between Dl and D2. For omitted 
parameters, full range (all traps, all addresses, all D@ values) used. 
These commands set up conditions that are monitored when Go is used. 


AB T] T2 Al A2 Di D2 Break on specified A-traps 
AT Tl T2 Al A2 Dl D2 Trace program and display specified A-traps 
AH Tl T2 Al A2 Dl D2 Check the heap on specified traps 


HS TI T2 Scramble heap and check it on specified traps 
Usually Tl=$18 and T2=$2D for optimal speed 
AS Al A2 Remember checksum for address range; validate it 


before traps 
AX Clear all A-Trap commands 
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Heap Commands 


HX Toggle between system heap and application heap 
HC Check the consistency of current heap 
HD MASK Dump each heap block, followed by heap summary line 


Block = BlockAddr Type Size [Flags MP location] [*] [RefNum ID Type] 


Type (of block): F = free, P = pointer, H = handle 
Size: physical size = headertcontents+spare bytes 
Flags nibble: Bit 3 = Locked; Bit 2 = Purgeable; 

Bit I = Resource; Bit ® = unused 
MP Location: the location of the Master Pointer 
*: indicates non-relocatable or locked blocks 
RefNum ID Type: given for resource blocks only 


If no MASK: 
Summary = HLP PF #Reloc blocks, fLocked reloc blocks, fPurgeable blocks, 
Purgeable space, Non-reloc blocks, Free Space 


If MASK = 'H' (handle), 'P' (pointer), 'F' (free blocks), 
'R' (relocatable), or 'xxxx' (resource type 'xxxx') then 
Summary = CNT ### <# of blocks of MASK type? Xf bytes in those blocks? 


HP MASK Dump heap to other port (TermBugA or TermBugB only) 
HT MASK Display heap dump summary line (See HD) 
Disassembier Commands 
ID À Disassemble one line at address À 
IL AN Disasseuble N lines starting at address A 
PX Toggles symbolic display (Pascal option only) 
Miscellaneous Commands 
FACDM Search C bytes from address A, looking for data D after 
masking the target with M. Display first occurrence 
WH X X<512: display address of trap X 
X>511: display trap nearest address X 
CS Al A2 Checksum specified range. If no A2, 16 bytes. If no Al 
or AZ, checksum and compare with last. Print result. 
CV X Display X as unsigned hex, signed hex, signed decimal 
and text 
RX Toggle register dísplay during trace 
Handy Hints 
SM PC 6@FE Enter instruction BRA *-2 to stop disk spinning 
SM PC 4E71 Enter no-op at current PC location 
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Glossary 


The terms in this glossary are defined in the context of the Macintosh 
68900 Development System. All references to the Assembler, Editor, 
Linker, RMaker, or PackSyms refer to applications in the development 
system. Things that are true of the Editor, Assembler, or Linker in 
this package are not necessarily true of other editors, assemblers, or 
linkers. 


application: A tool to manipulate information. Macintosh 68000 
Development System applications include the Editor, Assembler, Linker, 
Executive, Resource Compiler, and PackSyms. 


application heap: A portion of memory available to the application 
program for its own memory allocation. 


argument: In a macro definition, a placeholder for values that are 
supplied when the macro is actually used. Values are passed to the 
macro as a list of parameters; they replace, character-for-character, 
the arguments that represent them. 


assembler: An application that translates an assembly-language program 
(understandable by humans) into a form that is useful to a computer. 
The Assembler creates modules that can then be connected together, by 
the Linker, to form an application. 


assembly-language program: Lines of text containing instructions 
written by a human, translated by an assembler, and carried out by a 
computer. These instructions generally include instructions to the 
microprocessor, instructions to the assembler, and comments to humans. 


A-trap: An instruction beginning with a hexadecimal $A which, when 
executed by the MC68ØØØ, causes an exception. The Macintosh recognizes 
this exception as a call to one of its Operating System or Toolbox 
routines and uses it to determine which routine was reqested. Also 
called a system trap, or simply a trap. 


block: An area of contiguous memory within a heap zone. 


breakpoint: An instruction in an application that causes the immediate 
halting of the application. Using a debugger, you can place a 
breakpoint in an application; when the program halts, you can use the 
debugger to examine the state of the program. 


bundle: A resource that maps local IDs of resources to their actual 
resource IDs; used to provide mappings for file references and icon 
lists needed by the Finder. 


cell: In MacDB, an address or value that can be selected, and 
sometimes changed. 
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conditional assembly: The act of assembling a program that has 
conditions placed in it that determine whether or not specified blocks 
of source should generate code. In the Assembler the IF, ELSE, and 
ENDIF directives are used to perform conditional assembly. 


data fork: The part of a file that contains data accessed via the File 
Manager. 


debugger: An application that aids analysis of ailing applications. 
Debuggers generally provide a way to stop an application, to examine 
the computer's memory and registers, and to control the operation of 
the application. 


directive: An instruction within a file that {is interpreted as a 
command to the Assembler or the Linker. 


document: Whatever you create with Macintosh applications--information 
you enter, modify, view, or save. 


Editor: An application that lets you enter, modify, view, or save 
text, or some other form of Information. The Editor is a disk-based 
text editor that lets you create documents larger than will fit into 
memory. 


exception: An error or abnormal condition detected by the processor in 
the course of program execution. System traps are exceptions. Refer 
to the 68900 Reference Manual for more details. 


Executive: The Executive is an applícation that lets you control the 
use of other applications. If you repeatedly assemble, link, and add 
resources to the same files, you can use the Executive to automate the 
process. 


expression: A collection of symbols (numbers, labels, mathematical 
operators...) that is arranged according to a set of rules (syntax). 
The symbols are evaluated according to that set of rules to produce a 
result. 


extension: In the development system, a period followed by one or more 
letters that is added to a filename to help identify the type of 
information ín the file. 


frozen: A state in which the contents of a MacDB window cannot change. 
By default, MacDB windows are changeable (thawed). 


global space: An application's global space is a fixed block of memory 
that is located relative to Á5. It contains all the program storage 
declared using the DS directive. Because it never moves, it is ideal 
storage for data shared between segments. 


heap: An area of memory in which space is dynamically allocated and 
released on demand, using the Memory Manager. 
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jump table: A table that contains one entry for each routine that is 
used by more than one segment. It is a channel of communication 
between relocatable segments, and even allows segments to be removed 
from memory until called by the active segment. 


linker: In the development system, an application that connects .Rel 
files (produced by the Assembler) together into an application. 


machine language: The language that the microprocessor itself 
understands. The Assembler and Linker together translate an 
assembly-language program that you can understand into a 
machine-language program that the Macintosh can understand. 


macro instruction: Consists of a name and a list of parameters. When 
assembled, the macro call is replaced by the list of instructions it 
represents, and the parameters are placed into that list of 
instructions, as appropriate. Just as subroutines are a way of 
generalizing similar pieces of code, macros are a way of generalizing 
similar pieces of text. 


MacWorks: A program that runs on a Lisa computer and that allows the 
Lisa to run Macintosh software. 


modem port: On a Macintosh, the port that has the modem icon above it. 
Also known as port A. 


Nub: In the context of the development system, a program you should 
run on the Macintosh on which you wish to debug your program. MacDB, 
running on another Macintosh, can then examine your program by 
communicating with the nub over a serial cable. 


operand: A quantity upon which an operation is performed. In the 
expression A + B, the operands are A and B, and + is the operator. In 
the assembly-language instruction MOVE D9,Dl, the operands are DØ and 
DL. 


operator: A character or characters that represent an operation to be 
performed. Operators perform operations upon operands. 


packed symbol file: A file that equates values to symbols. Like a text 
file composed of EQU statements, but in a much more compact form. To 
create a packed symbol file, run PackSyms on a .Sym file. 


parameter: In a macro call, a text-string that is to be placed 
literally into the list of instructions that the macro represents. 
Each parameter replaces all instances of the argument that is a 
placeholder for it. 


Pascal string: A Pascal string starts on a word boundary. It consists 
of a byte containing the length of the string followed by bytes 
containing the ASCII codes of the characters in the string. 


precedence: In an expression, the order in which operations are 
performed. For example, in expressions used in the Assembler, 
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multiplication is performed before addition (with the exception that 
operations in parentheses are performed first). 


printer port: On a Macintosh, the port that has the printer icon above 
it. Also referred to as port B. The machine that runs the MacDB 
debugger must always be connected to the other machine by this port. 


program counter: The register in the 68000 that points to the memory 
address that contains the assembly-language instruction that is 
currently being executed. 


port A: On a Macintosh, the port that has the modem icon above it. 


port B: On a Macintosh, the port that has the printer icon above it. 
The machine that runs the MacDB debugger must always be connected to 
the other machine by this port. 


register: A structure within a microprocessor that holds information, 
that can be rapidly and flexibly changed or moved. The 68000 has data 
registers for general data manipulation, address registers that point 
to memory locations, and other registers crucial to the operation of 
the microprocessor. See also: program counter and stack pointer. 


relocatable: Moveable. The Assembler and Linker produce code segments 
that work regardless of their position in memory. The Segment Loader 
moves segments of code relative to one other by updating the jump table 
that allows communication between segments. Together, these features 
create relocatable applications. 


resource: Data or code stored in a resource file and managed by the 
Resource Manager. Predefined resource formats, such as menus or fonts, 
make possible the easy integration of complex data structures into an 
application. 


Resource Compiler: An application that forms resources from a set of 
definitions, and places them into a resource file. The RMaker 
application is the Resource Compiler; however, the Linker is also able 
to create resources. 


resource fork: The part of a file that contains the resources used by 
an application (such as menus, fonts, and icons) and also the 
application code itself; usually accessed via the Resource Manager. 


RMaker: See Resource Compiler. 


segment: One of several parts into which the code of an application 
may be divided. Not all segments need to be in memory at the same 
time. 


source file: A file that contains information used as input to an 
application. 


stack: An area of memory in which space is allocated and released in 
LIFO (last-in-first-out) order, used primarily for routine parameters, 
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return addresses, local variables, and temporary storage. 


stack pointer (SP): A register that contains the memory address that 
is currently the top of the stack. In the 68000, address register 7 
(A7) is used as the stack pointer. 


symbol table: Data that represents the symbols (variables, constants, 
labels, and routine names) used by a program. The symbol table is 
created by the Assembler and used by the Linker. 


system definition file: A file defining global constants, variables, 
or system traps. The development system is shipped with a set of 
equates files and traps files that contain necessary system 
definitions. 


system heap: A portion of memory reserved for use by the Macintosh 
system software. 


text-only file: A file consisting of a stream of ASCII characters that 
contains no special formatting information. 


thawed:  Describes a MacDB window that can be changed. A MacDB window 
that cannot be changed is said to be frozen. 


trace: To examine, one instruction at a time, the execution of a 
program. The MacDB Trace command executes the machine-language 
instruction indicated by the program counter, then it updates its 
windows. 


trap: See A-trap. 
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A 
address 31 
aligning 42 
addressing modes 31 
alert 
item 97 
template 96 
+ALIGN directive 43 
align box 65, 71 
aligning 
addresses 42 
columns 21 
anchor box 65 
Anchor command 65, 70 
appending to resource file 94 
application bundle 96 
arguments, macro 38 
.Asm 19, 25 
file list 25 
files 28 
Assembler 8, 25 
directives 35 
errors 8, 133 
file naming conventions 25 
invoking 26 
macros 8 
output files 29 
source files 26, 28 
syntax 29 
assembly-language source programs 25 
asterisk (*) 30, 69 
A-Trap command(s) 72-73, 86 
attribute byte 44 
Auto Indent command 21 
auto-pop bit 73 


B 

.B extension 32 
binary notation 33 
Bkpts menu 69 
block header 73 
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branch instructions 32 
breakpoint 69 
Breakpoints window 64 


C 
cells 66 
Change command 21 
changing text 21 
Char command 71 
Clear All command 69 
Clear command 69 
close box 65 
code optimization 32 
columns, aligning 21 
Command-S 29 
comments 
Assembler 30 
RMaker 93 
Compile command 100 
Control 
commands 83 
template 96 
copying text 21 
creator bytes 51, 93-94 
current program location 30 
cutting text 21 


D 
D file 25, 45 
/Data command 51, 53 
data fork 49, 52 
data registers 3l 
data storage 52 
DC directive 41 
DCB directive 42 
debug machine 61 
Debug menu 67 
Debugger See MacDB; MacsBug 
decímal notation 33 
default 

font 20 

volume 28 
defined resource types 95 
dialog resource 97 
directives 

Assembler 35 

Linker 43 

printing control 27, 35 
Disassembler commands 88 
disk-based editor 20 
disk drive, stopping 67, 89 
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document 
opening 20 
printing 22 
DS directive 42 
.DUMP directive 40, 44 
Duplicate command 69 


E 
editing 21 
Editor 7, 19 
document names 7 
documents 7, 20 
file naming conventions 19 
invoking 19 
‚EJECT directive 35 
ELSE directive 37 
END directive 40 
ENDIF directive 37 
.ENDM directive 39 
EQU directive 40 
equates 16 
.Err file 26, 29 
errors 
Assembler 8, 133 
Executive 58 
Linker 9, 135 
RMaker 137 
Examine window 64 
exceptions 62, 63, 78, 79 
Execute command 58 
Executive 10, 57 
control file 57 
default name 58 
errors 58 
file naming conventions 57 
invoking 57 
syntax 57-58 
using 58 
expressions 33 
MacsBug 81 


F 

file 
name 28 
naming conventions 6 
opening from Editor 20 
selecting from Assembler 27 
setting creator 51, 93-94 
setting type 51, 93-94 

file reference 98 

file system equates 16 

«Files 19, 25 

„Files files 28 


Filter by Time command 27 
Find command 21 
finding text 21 
512K Mac command 6/ 
font 
default 20 
monospaced 20 
proportional 21 
Format menu 71 
Frozen command 70 


G 

global equates 16 

global storage 4l, 49, 52 
{Globalis command 51, 52 
Go Till command 68 

Go To command 68 


H 
Heap Check Off command 67 
Heap Check On command 67 
heap zone 71 

commands 86 
Hex Address command 70 
hexadecimal notation 33 


I 
IF directive 37 
INCLUDE directive 36, 94 
indenting text 21 
initial volume 28 
Inside Macintosh 3 
Inst command 71 
instruction 30 

lines, Assembler 29 

syntax, Assembler 30 
interrupt button 79 
invoking 

Assembler 26 

Editor 19 

Executive 57 

Linker 50 

MacDB 61 

MacsBug 77, 79 

RMaker 100 
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«Job 19, 57 

.Job files 10, 58 
jump instructions 32 
jumb table 49 
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L 
‚L extension 32 
labels 30, 42 
»LErr 49 
«Link 19, 49 
linked list 72 
Linker 9, 49 
commands 50 
control directives 43 
control file 50, 52 
errors 9, 135 
file naming conventions 49 
invoking 50 
sample control file 53 
Lisa Workshop 90, 93 
LisaBug 78 
list of .Asm files 25 
List command 72 
List to Display command 27, 29 
List to File command 27, 29 
listing, Assembler 27 
.ListToDisp directive 35 
«ListToFile directive 35 
local label 30 
Long command 71 
lowercase letters 29 
«Lst file 26, 29 


M68000 16/32-Bit Microprocessor 


Programmer's Reference Manual 3 
MacDB 12-13, 61 


menus 67 

windows 63 
Macintosh, the owner's guide 3 
Macintosh 68000 Development System 

disks 4 
MacNub 62 
MACRO directive 39 
MACRO 38 
macros 38 

Lisa-style 39 

for numerics 16 

for packages 16 
MacsBug 12, 14, 77-78 

commands 81 

invoking 79 

setting up 77 

syntax 80 

versions 77 
MacWorks 61, 78 
.Map file 9, 49, 73, 74 
master pointer 73, 86 
MaxBug 78 
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MDS1 disk 4 
MDS2 disk 5 
MemBlock command 73 
Memory commands 81 
memory storage 42 
menu(s) 98 

defining 54 

MacDB 67 
miscellaneous MacsBug commands 88 
modes, addressing 31 
monospaced font 20 
Move Left command 21 
Move Right command 21 
MOVEM command 3i 


N 
naming 
Assembler files 25 
Editor files 19 
Executive files 57 
files 6 
Linker files 49 
resource files 93 
New command 69 
new document 20 
No Anchor command 65, 70 
No Listing command 27 
.NoList directive 35 
non-string expression 37 
no-op 67, 90 
Normal Output command 27 
/NoUndef command 51 
.NoVerbose directive 35 
/NoVerbose command 51 
Nub 12, 61-62, 63 
numbers 33 
MacsBug 80 


0 
octal notation 33 
128K Mac command 67 
Open command 20 
Open Job File command 58 
opening 

document 20 

files 20 
operations 34 
operators, MacsBug 81 
/Output command 51, 52 
output file 52 
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package equates 16 
package macros 16 
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packed symbol files 44, 45 
PackSyms 44 
Pascal String command 71 
PC window 63 
precedence 34 
Print command 22 
printer equates 16 
printing 
control directives 27, 35 
dialog box 22 
document 22 
procedure 98 
Proceed command 63, 68 
program, sample 103 
proportional font 21 
Purge command 74 


Q 
QuickDraw equates 16 
QuickDraw traps 16 


R 
eR file 19, 25, 93, 100 
«R Filter command 100 
REG directive 41 
Register commands 82 
Registers window 63 
.Rel file 8, 9, 29, 41, 53, 93 
removing text 21 
replacing text 21 
Resource Compiler See RMaker 
RESOURCE directive 44, 53 
resource files 93 

adding to 94 

naming 93 

types 95 
resource fork 49, 52 
resources 49, 95 

defining 53 

types of 99 
/Resources command 51, 52, 53 
Resume command 58 
Resume and Re-do Last command 58 
RMaker 15, 93 

creating types 99 

errors 137 

input file 93 

syntax 95-96 

using 100 
replacíng 21 
.Rsrc files 93 
Run menu 68 


S 
sample 
Linker control file 53 
program 103 
session ll 
Sample Programs folder li 
scope 30 
scroll 
arrows 66 
bars 20, 66 
box 66 
Search command 72 
searching for source files 28 
Select File command 27 
selecting 
listing options 27 
source files 27 
SET directive 41 
Set command 69 
Set Startup command 62 
Set Tabs command 21 
setting 
file's creator 51, 93-94 
file's type 51, 93-94 
setting up 
MacsBug 77 
Debugger 61 
signature bytes 51, 93-94 
size box 66 
size extension 32 
source files 
Assembler 26, 28 
Editor 7, 20 
Executive 57 
Linker 50, 52 
RMaker 93 
start box 65 
stopping 
assembly 29 
disk drive 89 
listing 29 
STRING_FORMAT 36 
strings 33, 36-37, 98 
.Sym file 26, 40, 44, 74 
symbol table 9 
Symbolic Address command 70 
symbols 34, 74 
MacsBug 80 
Symbols menu 73 
syntax 
Assembler 29 
Executive 57-58 
MacsBug 80 
RMaker 95-96 
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system definition files 16 
system error numbers 16 
system traps 72, 84 
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tab stops 21 

target machine 61 
template 96 

TermBugA 78 

TermBugB 78 

text literals, MacsBug 80 
text-only files 7, 22, 26 
Thawed command 70 

title bar 65 

Title command 70 

Toolbox equates 16 
Toolbox traps 16 

TP 80 

Trace command 68 

Trace Into ROM command 68 
»TRAP directive 41 

traps 16, 72-73, B4 

type bytes 51, 93-94 
{Type command 51 

typing text 20 


U 
/UndefOK command 51 
uppercase letters 29 
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v 
Value command 74 
.Verbose directive 35 
/Verbose command 50 
Verbose Output command 27 
volume 

default 28 

names 6, 28 


W 
W extension 32 
Wait command 67 
Window menu 69 
window(s) 
Breakpoints 64 
Examine 64 
MacDB 63 
PC 63 
Registers 64 
template 99 
word alignment 42 
Word command 71 
WorksNub 61 
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XDEF directive 43 
XREF directive 43 
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